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This reference book covers the programming interface for Workplace 
Shell in OS/2 versions 2.1 and 3.0. There are two major features that 
make this book distinctive from other Workplace Shell references—its 
organization and level of detail. 

As with the other books in this series, the information is organized 
by subject to make this book as usable as possible. This is advantageous 
for both beginners and experts. A beginner typically knows what func¬ 
tionality he or she wants to implement, but not necessarily the names 
of the desired methods. Each chapter covers a specific topic; this allows 
a beginner to quickly access information about all the methods rele¬ 
vant to the task at hand. An advanced programmer typically imple¬ 
ments features one category at a time and, therefore, will find this 
book’s topic-oriented organization useful. 

This book is written by a Workplace Shell programmer for 
Workplace Shell programmers, ensuring a high level of detail in the in¬ 
formation presented. I have included hints and tips that I have learned 
through my experiences writing Workplace applications and working 
on the Workplace Shell development team. 

One consequence of the level of detail is that basic information 
about Presentation Manager (PM) programming, as well as System 
Object Model (SOM) concepts, is outside the scope of this book. 
Knowledge of these topics, as well as a complete understanding of C or 
C++, is a prerequisite for Workplace Shell programming. It is also help¬ 
ful to have a working knowledge of how to use OS/2 and the 
Workplace Shell interface. Furthermore, this book does not explain 
step-by-step how to design a Workplace Shell subclass; instead, the 
book focuses on providing thorough descriptions of each method. 
Writing SOM and, especially, Workplace Shell applications can be very 
difficult at first, and beginners should refer to the WPCar sample in¬ 
cluded in the OS/2 Developer’s Toolkit as a guide for designing a subclass. 
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Notes 


# The samples in this book are written using C. C++ programmers can 
still make use of this code, keeping in mind that the syntax for in¬ 
voking methods is different. For example: 

_wpViewObject(Object, NULLHANDLE, OPEN_DEFAULT, 0); /* C syntax */ 

Object->wpViewObject(NULLHANDLE, OPEN_DEFAULT, 0); /* C++ syntax */ 

i In C the first parameter of each SOM method is always somSelf. 
Throughout this book the somSelf parameter is assumed and is not 
specifically listed. 

# The structure definitions include the offset of each field listed in the 
right column of the page. 
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T o the user, Workplace Shell is the entire user interface of OS/2. 

This includes folders, objects, notebooks, containers, drag/drop, 
and so on. From a programming perspective, this view is not entirely 
accurate. The Presentation Manager (PM) APIs provided by OS/2’s 
Window Manager provides the basic GUI programming environment 
necessary for writing an application. This includes the 1.x controls 
such as frames, buttons, scroll bars, and list boxes as well as the newer 
controls such as notebooks, containers, and drag/drop. Therefore, 
any PM application can take advantage of these controls without nec¬ 
essarily being a Workplace Shell application. Even the Workplace Shell 
itself, for example, is just a special PM application that is automatically 
run when the operating system starts. 

The Workplace Shell was implemented using IBM’s System Object 
Model (SOM), a language-independent interface that allows programs 
to be written using object-oriented techniques. The Workplace Shell 
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API makes available to the programmer all the public classes imple¬ 
mented in the user interface (folders, programs, data files), the ability 
to subclass them, and the means to reuse and modify their behavior. 
Therefore, to a programmer, a Workplace Shell application is one that 
takes advantage of existing Workplace classes by using SOM to create a 
subclass. This subclass becomes a fully integrated part of the shell with 
its own unique behavior. The benefit of creating a Workplace applica¬ 
tion over a PM application is that a Workplace Shell object can make 
use of the pop-up menu, settings notebook, and drag/drop behavior 
already implemented by its parent class. 

Workplace Shell subclasses are written using SOM and C or C++ 
and are then compiled into Dynamic Link Libraries (DLLs). Any user- 
defined class can be added to the Workplace Shell interface by regis¬ 
tering the DLL that contains the class definition source code using 
WinRegisterObjectClass (pg. 18). When a Workplace class is loaded, it 
automatically becomes part of the PMSHELL.EXE process. 

Predefined Workplace Classes 

Since Workplace Shell programming is all about subclassing existing 
classes, it is imperative to be aware of all the classes provided and how 
they behave. Because Workplace classes derive behavior from one an¬ 
other, they are arranged in a hierarchical fashion. All Workplace 
classes are descendants of WPObject, the class that provides the de¬ 
fault basic behavior of all objects. (Note that all predefined Workplace 
classes that ship with OS/2 have the prefix ‘WP’.) There are three di¬ 
rect subclasses of WPObject; these base classes provide different stor¬ 
age mechanisms for the data of each of its objects (see Figure 1.1). 


SOMObject 

-SOMCIass 

-SOMCIassMgr 

-WPObject 

-WPAbstract 

-WPFileSystem 

-WPTransient 


FIGURE l.l 

Workplace base class hierarchy. 
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Since the base classes define storage mechanisms, they are sometimes 
referred to as storage classes. 

WPAbstract Object instance data is stored in the user ini file 

(OS2.INI). They are not stored anywhere else in the 
file system. 

WPFileSystem Objects represent real files or directories that reside in 

the directory structure that matches the parent folder 
hierarchy. Instance data is stored in the Extended 
Attributes (EAs) of the file. 

WPTransient Objects are not persistent and do not save their 

instance data. When the machine is rebooted, the 
objects will not reappear. 

Instances of WPObject or the three base classes cannot be created. 
All other predefined Workplace classes can be instantiated. Defining 
your own base class is currently not supported in OS/2, therefore, all 
Workplace classes are descendants of these base classes (see Figure 1.2). 
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A lot of thought should be given to choosing the best base class from 
which to inherit. If instances will be created for temporary use and can 
be re-created easily, the class should inherit from WPTransient. Also 
consider whether it will be necessary to move instances onto diskettes 
or across the LAN. WPFileSystem is the only base class whose descen¬ 
dants have this capability. WPAbstract should be subclassed if instances 
must persist after the machine has been rebooted but would not neces¬ 
sarily make sense to be in the file system. 

All Workplace classes provide new behavior different from their 
respective parent classes (see Figure 1.2). Some classes do not define 
public methods; however, instances of such classes can still be created, 
and methods from their parent classes can be invoked. Furthermore, 
many of these classes define setup string keywords (see Appendix A) to 
enable the application to customize their instances. 

The device classes WPMouse, WPKeyboard, and WPSystem do not 
define public methods other than the settings page methods listed in 
Appendix C. However, they do provide setting strings that can be 
passed to wpclsQuerySetting (pg. 126) and wpclsSetSetting (pg. 131). 

Replacing a Class 

Classes can be added to Workplace or can completely replace exist¬ 
ing classes. Replacing a class forces all existing objects of the re¬ 
placed class to take on the behavior of the user-defined class. (See 
WinReplaceObjectClass pg. 19) The classes WPMouse, WPCountry, 
WPKeyboard, WPSound, WPClock, WPShredder, WPPower, and 
WPSystem are the device classes, each of which is not reentrant and 
has exactly one instance that cannot be deleted. Consequently, these 
classes must be replaced in order to modify their behavior. Be aware 
that if multiple instances of these device classes are created, no error 
message is given, but unpredictable results will occur and will probably 
confuse the user. 

General Restrictions and Warnings 

• You cannot call a class method on an instance pointer or an instance 
method on a class object pointer. Class methods in the Workplace 
Shell are named with the prefix ‘wpcls’ and instance methods have 
the prefix ‘wp’. For example, if you override wpclsfnitData, the 
somSelf parameter is a class object pointer, and you cannot use it to 
call an instance method, such as wpAllocMem (a common mistake 
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among first time Workplace Shell programmers). If a class pointer is 
needed to invoke a class method, call somGetClass (pg. 345) on an 
instance pointer. 

m Workplace is designed such that all objects must be created inside a 
folder. If an object is not designed to be contained in a folder, it can 
be created in the Nowhere folder, or <WP_NOWHERE>, where it 
will not be visible. 

• When calling methods from an application-defined thread, you 
must first create a message queue for that thread. 

® Since all classes run under the Workplace process, it is good practice 
to keep processing in method overrides short or multithreaded. It is 
also recommended that classes implement their own exception han¬ 
dling to prevent the entire shell from trapping when an exception 
occurs. 




Installin 
Workplace 
Classes 


W orkplace classes cannot be used until they have been registered 
with the Workplace Shell. Unfortunately, the OS/2 default sys¬ 
tem does not come with a mechanism for users to register classes. 
Therefore, the developer of the class DLL must provide this function¬ 
ality with an installation program. 

An installation program for a Workplace class will generally be a 
stand-alone Presentation Manager executable or a REXX program. 
Most installation programs will first use Control Program functions 
to copy the class DLL onto the user’s machine, and then call 
WinRegisterObjectClass to register the class with the system. 
WinRegisterObjectClass accepts a fully qualified path of the class DLL 
location; therefore, the class can either be installed in the LIBPATH of 
the system or in any directory. Once the class has been successfully reg- 
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istered, the installation program can also use WinCreateObject to cre¬ 
ate instances of the class or other classes on the desktop. 

A deinstall program should also be provided to enable the user 
to deregister the class. See WinDeregisterObjectClass for more infor¬ 
mation. 


Manipulating Objects from a Separate Process 

All Workplace Shell classes execute in the same PMSHELL.EXE pro¬ 
cess and can therefore manipulate other Workplace objects using the 
SOM methods described in other chapters in this book. There are a 
small number of functions that work across processes and can be 
called from any Presentation Manager executable. These functions, 
listed in this chapter, allow programs to register and deregister classes; 
create, destroy, copy, and move objects; and set object data. Most of the 
functions correspond to Workplace SOM methods and have REXX 
equivalents provided in the REXXUTIL.DLL that ships with OS/2. 


Object Handles and IDs 

When a Workplace object is created using WinCreateObject, it is as¬ 
signed a unique number called an object handle. These handles are 
persistent across boots of the machine and can always be used to access 
the objects they refer to. The object handle is used as a parameter or 
return code for many of the Workplace APIs to enable applications to 
uniquely identify the objects. 

Objects can also be assigned object IDs as identifiers. Object IDs 
are strings beginning with *<’ and ending with *>’. For example, the ob¬ 
ject ID for the desktop is ‘<WP_DESKTOP>’. Applications assign object 
IDs by using the OBJECTID keyname in the setup string parameter. 
Since object IDs are generated by the application, they are not guaran¬ 
teed to always be unique. If you use an object ID that is a duplicate, you 
risk replacing an existing object or mistaking a different object for your 
own. Applications should include their application names in the object 
IDs to help ensure uniqueness. 


Restrictions and Warnings 

• Currently there is no interface for querying object data from a sep¬ 
arate executable. 
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m Object IDs should be used sparingly because they are application¬ 
generated strings that must be unique in the system. Whenever pos¬ 
sible, save the object handles instead. 

• The REXX Workplace APIs accept only object IDs as parameters. 
Therefore, REXX programs must use object IDs to uniquely identify 
objects. 

• There is no REXX API for replacing an object class. 


PM Functions 


WinCopyObject (Warp) copies a Workplace object (pg. 8). 
WinCreateObject creates a Workplace object (pg. 9). 
WinCreateShadow (Warp) creates a shadow of a Workplace object 
(Pg- U). 

WinDeregisterObjectClass deregisters a Workplace class (pg. 12). 
WinDestroyObject deletes a Workplace object (pg. 13). 
WinEnumObjectClasses enumerates all registered Workplace classes 

(Pg- 14 )- 

WinMoveObjject (Warp) moves a Workplace object to another folder 

(pg. 16). 

WinOpenObject (Warp) opens a view of a Workplace object (pg. 16). 
WinQueryObject returns the handle of an object (pg. 17). 
WinRegisterObjectClass registers a Workplace object class (pg. 18). 
WiuReplaceObjectClass replaces an existing Workplace class (pg. 19). 
WinSaveObject (Warp) notifies an object to save its data (pg. 21). 
WinSetObjectData sets instance data on an object (pg. 22). 


• WinCopyObject (Warp only) 

Copies a Workplace object. 

SYNTAX 

HOBJECT WinCopyObject (HOBJECT hObjectOfObject, HOBJECT 

liObjectOjDest, ULONG ulReserved ) 
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PARAMETERS 

hObjectOfObject - input 

The object handle of the object to be copied. Object handles can be 
obtained by calling WinQueryObject or by saving the handle when it is 
returned by WinCreateObject. 
hObjectOfDest - input 

The object handle of the folder in which to place the new copy. 
ulReserved - reserved 
Set this parameter to 0. 

RETURNS 

(nonzero value) - The object handle of the new copy. 

NULLHANDLE - The copy operation failed. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCreateObject -9, WinCreateShadow -11, WinMoveObject -16, 
WinQueryObject -17, wpCopyObject -44 

NOTES 

If an object exists in the destination folder with the same title as the 
new copy, the copy operation will fail. 


# WinCreateObject 


Creates a Workplace object of the specified class. 

SYNTAX 

HOBJECT WinCreateObject (PSZ pszClassName, PSZ pszTitle, PSZ pszSet- 

upString, PSZ pszLocation, ULONG ulFlag) 

PARAMETERS 

pszClassName - input 

The name of the class for the new object. This must be a registered 
Workplace Shell class. See the class hierarchy (pg. 3) for the list of pre¬ 
defined Workplace Shell classes. This parameter is case-sensitive. 
pszTitle - input 
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The title for the new object. 
pszSetupString - input 

The initial settings for the new object. A setup string is a list of key¬ 
name value pairs separated by semicolons which is parsed by the object 
for initialization. Specify NULL to use the object’s defaults. See 
Appendix A for the list of possible keyname value pairs for the prede¬ 
fined Workplace Shell classes. For more information on setup strings, 
see wpSetup (pg. 63). 
pszLocation - input 

The folder location for the new object. This can either be the object 
ID (if it exists and is known) or the fully qualified path of the direc¬ 
tory represented by a folder. For example, to create an object on the 
Desktop, pszLocation would either be “<WP_DESKTOP>” or 
“C:\DESKTOP” (assuming the Desktop is on the C drive and is called 
‘Desktop’). See Appendix D for a list of predefined folder object IDs. 
ulFlag - input 

This flag specifies what action should be taken if a duplicate existing 
object is found. If an object ID is specified in pszSetupString and an ex¬ 
isting object with that ID is found or an existing object with the same 
title in the same folder is found, that object is considered a duplicate. 


Constant 


Description 

CO_FAILIFEXISTS 

0x00 

If a duplicate is found, the new 
object is not created and the call 
will fail. 

CO_REPLACEIFEXISTS 

0x01 

If a duplicate is found, the new 
object is created and replaces the 
duplicate. 

COJUPDATEIFEXISTS 

0x02 

If a duplicate is found, the new 
object is not created and, if 
specified, pszSetupString is passed to 
the duplicate as if 
WinSetObjectData were called. 


RETURNS 

(nonzero value)—The handle to the newly created object. 
NULLHANDLE—object creation failed. 
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OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinDestroyObject -13, WinRegisterObjectClass -18, 

WinSetObjectData -22, wpSetup -63, wpclsNew -71 

NOTES 

The class name specified in pszClassName must be a registered Workplace 
Shell class. You must use either a predefined Workplace Shell class or a 
class that has been registered with WinRegisterObjectClass. 

When this function is called, Workplace Shell will call wpclsNew 
on the specified class object to create the new instance. 

SAMPLE CODE 

#define INCL_WINWORKPLACE 
#include <os2.h> 


HOBJECT hObject; 

/* create a folder object on the desktop named 'My Folder' that is 
not deleteable 

* and assign it the object ID, <MY_FOLDER>. 

*/ 

hObject = WinCreateObject ("WPFolder", //class name 

"My Folder", // title of new object 
"<WP_DESKTOP>", // place object on the 
desktop 

"NODELETE=YES;OBJECTID=<MY_FOLDER>", 
CO_FAILIFEXISTS); 


# WinCreateShadow (Warp only) 

Creates a shadow of a Workplace object. 

SYNTAX 

HOBJECT WinCreateShadow (HOBJECT hObjectOfObject, HOBJECT 

hObjectOJDest, ULONG ulReserved) 
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PARAMETERS 

hObjectOf Object - input 

The object handle of the object to be shadowed. Object handles can be 
obtained by calling WinOueryObject or by saving the handle when it is 
returned by WinCreateObject. 
hObjectOfDest - input 

The object handle of the folder in which to place the new shadow. 
ulReserved - reserved 
Set this parameter to 0. 

RETURNS 

(nonzero value)—The object handle of the new shadow. 
NULLHANDLE—The operation failed. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCopyObject -8, WinCreateObject -9, WinMoveObject -16, 
WinQueryObject -17, wpCreateShadowObject -50 

NOTES 

If an object exists in the destination folder with the same title as the 
new shadow, the operation will fail. 


• WinOeregisterObJectCSass 


Deregisters an application-defined Workplace class. 

SYNTAX 

BOOL WinDeregisterObjectClass (PSZ pszClcissName) 

PARAMETERS 

pszClassName - input 

The name of the class to deregister. Predefined Workplace Shell 
classes cannot be deregistered. This parameter is case-sensitive. 

RETURNS 

TRUE—The class deregistered successfully. 

FALSE—An error occurred. 
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OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinDestroyObject-13, WinEnumObjectClasses -14, 
WinRegisterObjectClass -18 

NOTES 

This function should be used to deregister Workplace Shell classes that 
have been registered using WinRegisterObjectClass. Classes should be 
deregistered by deinstall programs for applications. When the class is 
deregistered, the DLL is unloaded. This function will fail if any objects 
of the class are awake. See Chapter 3 for more information on what it 
means for an object to be awake. 

RESTRICTIONS 

It is the application’s responsibility to first remove any objects of the 
class to be deregistered. 


® WinDestroyObject 

Deletes a Workplace object. 

SYNTAX 

BOOL WinDestroyObject (HOBJECT hObject ) 

PARAMETERS 

hObject - input 

The persistent handle of any object. Even if the object has the style 
OBJSTYLE NODELETE, WinDestroyObject will still delete it (object 
styles only prevent the user from manipulating objects). Object han¬ 
dles can be obtained by calling WinQueryObject or by saving the han¬ 
dle when it is returned by WinCreateObject. 

RETURNS 

TRUE—The object was successfully deleted. 

FALSE—.An error occurred. 


OTHER INFO 

Include file: pmwp.h 


Define: INCL_WINWORKPLACE 
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SEE ALSO 

WinCreateObject -9, WinQueryObject -17, wpFree -53, 
wpModifyStyle -108 

NOTES 

When this function is called, Workplace Shell will call wpFree on the 
object to delete it. If wpFree fails, the call to WinDestroyObject will re¬ 
turn FALSE. 

Folders will automatically delete their contents when they are de¬ 
stroyed. (See wpFree for details.) 

SAMPLE CODE 

#define INCL_WINWORKPLACE 
#include <os2.h> 

HOBJECT hObject; 

BOOL bSuccess; 

hObject = WinQueryObject("<WP_GAMES>"); /* get the handle of the 

games folder */ 

if (hObject) 

bSuccess = WinDestroyObject(hObject); /* now delete it */ 


® WlnErtumObJectClasses 


Enumerates all registered Workplace classes. 

SYNTAX 

BOOL WinEnumObjectClasses (POBJCLASS pObjClass, PULONG pSize) 

PARAMETERS 

pObjClass - input/output 

A pointer to a block of data that will be filled with a linked list of OBJ- 
CLASS structures (pg. 36). If a NULL value is passed, the required size 
for the buffer is returned in pSize. 
pSize- input/output 

If pObjClass is nonzero, pSize should be set to point to the size of the 
pObjClass buffer. If pObjClass is NULL, the required size for the buffer 
is returned. 
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RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinDeregisterObjectClass -12, WinRegisterObjectClass -18 

SAMPLE CODE 

#define INCL_WINWORKPLACE 
#include <os2.h> 

POBJCLASS pObjClass, pCurrentClass; 

ULONG ulSize; 

BOOL bSuccess; 

/* first call WinEnumObjectClasses to get the required size for 
* the buffer. 

*/ 

bSuccess = WinEnumObjectClasses(NULL, &ulSize); 
if (bSuccess && ulSize) 

{ 

pObjClass = (POBJCLASS) malloc(ulSize); 
if (pObjClass) 

{ 

bSuccess = WinEnumObjectClasses(pObjClass, &ulSize); 

/* access the buffer and free it when finished */ 
for (pCurrentClass = pObjClass; pCurrentClass; 
pCurrentClass = pCurrentClass->pNext) 

{ 

/* insert code to access class structure pCurrentClass is 
pointing to */ 

} 

/* free the pointer */ 
free(pObjClass) 

} 


} 
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® WinMoveObJect (Warp only) 

Moves a Workplace object. 

SYNTAX 

HOBJECT WinMoveObject (HOBJECT hObjectOfObject, HOBJECT 

hObjectOfDest, ULONG ulReserved) 


PARAMETERS 

hObjectOfObject - input 

The object handle of the object to be moved. Object handles can be 
obtained by calling WinQueryObject or by saving the handle when it is 
returned by WinCreateObject. 
hObjectOfDest - input 

The object handle of the new folder location for the specified object. 
ulReserved - reserved 
Set this parameter to 0. 

RETURNS 

(nonzero value)—The object handle of the object moved (same as 
hObjectOfObject). 

NULLHANDLE—The move operation failed. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCopyObject -8, WinCreateObject -9, WinCreateShadow -11, 
WinQueryObject -17, wpMoveObject -16 

NOTES 

If an object exists in the destination folder with the same title, the 
move operation will fail. 


# WinOpenObject (Warp only) 


Opens a view of a Workplace object. 
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SYNTAX 

BOOL WinOpenObject (HOBJECT hObject, ULONG ulView, BOOL 

Flag) “ 


PARAMETERS 

hObject- input 

The object handle of the object to open. Object handles can be ob¬ 
tained by calling WinQueryObject or by saving the handle when it is 
returned by WinCreateObject. 
ulView - input 

The value representing the view to open for this object. See Appendix 
E for a list of predefined Workplace views. The view constants are de¬ 
fined in wpobject.h. 

Flag - input 

When set to TRUE, the view will be opened following the window open 
behavior of the object. If the object does not support concurrent views 
and the view specified is already opened, the existing view will be sur¬ 
faced. When set to FALSE, a new view will always be opened. 

RETURNS 

TRUE—The view was opened successfully. 

FALSE—The open operation failed. 

OTHER INFO 

Include file: pmwp.h and wpobject.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinQueryObject -17, WinSetObjectData -22, wpOpen -160, 
wpViewObject -174 


® WinQueryObject 


Returns the persistent handle of an object given an object ID. 

SYNTAX 

HOBJECT WinQueryObject (PSZ pszObject) 

PARAMETERS 

pszObject- input 
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The object ID of an existing Workplace Shell object or the fully quali¬ 
fied path of a WPFileSystem object. For example, to obtain the object 
handle of the Desktop, pszObject would be either “<WP_DESKTOP>” 
or “C:\DESKTOP” (assuming the Desktop is on the C drive and is 
called ‘Desktop’). See Appendix D for a list of the object IDs of 
Workplace predefined objects. 

RETURNS 

(non zero value)—The class replacement was successful. 
NULLHANDLE—The object was not found or an error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCopyObject -8, WinCreateObject -9, WinCreateShadow -11, 
WinDestroyObject -13, WinMoveObject -16, WinOpenObject -16, 
WinSetObjectData -22, WinSaveObject -21 

NOTES 

Many functions described in this chapter accept only object handles as 
parameters. Therefore, WinQueryObject can be used to determine 
object handles when only the object ID or fully qualified path is 
known. 


• WinRegisterObjectCIass 


Registers an application-defined Workplace class. 

SYNTAX 

BOOL WinRegisterObjectCIass (PSZ pszClassName , PSZ pszModuleName) 

PARAMETERS 

pszClassName - input 

The name of the class to register. This parameter is case-sensitive, and 
the name of the class must be unique in the system. 
pszModuleName - input 

The name of the DLL that contains the class definition. This can be a 
fully qualified path or just the name of a DLL in the LIBPATH. 
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RETURNS 

TRUE—The class registered successfully. 

FALSE—An error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCreateObject -9, WinDeregisterObjectClass -12, 
WinEnumObjectClasses -14, wpPopulate -242 

NOTES 

Workplace classes only need to be registered once. The class will be 
added to the system class table which is stored in the system ini file. 
When registering a class contained in a DLL not in the system 
LIBPATH and the full path of the DLL is not specified, Win- 
RegisterObjectClass will return 0 but the class will still be added to the 
class list. This is convenient for applications that place DLLs in a new di¬ 
rectory and modify the LIBPATH statement in the CONFIG.SYS to con¬ 
tain this new directory, because this change will not take effect until the 
next reboot. However, in this situation, instances of this class cannot be 
created until after a reboot. If you are overriding wpclsQuerylnstance- 
Type or wpclsOuerylnstanceFilter, the class must be in the LIBPATH, or 
a full path must be specified when it is registered. 

When WinRegisterObjectClass is called and the class DLL is suc¬ 
cessfully loaded, Workplace calls wpPopulate on the Templates folder; 
this causes a template of the newly registered class to be created (the 
wpclsCreateDefaultTemplates method is called). 


® WinRepIaceObJectCIass 


Replaces an existing Workplace class with a user-defined class. 

SYNTAX 

BOOL WinReplaceObjectClass (PSZ pszOldClassName, PSZ pszNewClass- 

Name , BOOL bReplace) 


PARAMETERS 

pszOldClassName - input 
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The name of the class to replace. The class must be a registered 
Workplace class. This parameter is case-sensitive. 
pszNewClassName - input 

The name of the application-defined class that will replace the behavior 
of pszOldClassName. pszNewClassName must be a registered Workplace 
class and must be a direct descendant of pszOldClassName. This para¬ 
meter is case-sensitive. 
hReplace - input 

Set to TRUE to replace pszOldClassName with pszNewClassName. Set to 
FALSE to stop replacing pszOldClassName with pszNewClassName if such 
a replacement exists. 

RETURNS 

TRUE—The class replacement was successful. 

FALSE—An error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinDeregisterObjectClass -12, WinEnumObjectClasses -14, 
WinRegisterObjectClass -18 

NOTES 

A class is replaced to change the behavior of all the existing and future 
objects of that class. It is used to make global changes on objects of a spe¬ 
cific class. When you replace the parent class with your class, all instances 
of the replaced class become instances of your class. Furthermore, all 
subclasses of the parent class will inherit from your class. 

The word replace is misleading because it implies the parent class is 
removed from the parent chain and replaced with yours. This is not the 
case. The parent class remains and the new class is inserted after it in the 
class hierarchy. Furthermore, when an application creates an instance of 
the replaced class, the new class is used instead. For example, if Classes 
B, C, and D are subclasses of Class A, and B replaces A, then each time 
an instance of A is created, it will instead become an instance of Class B. 
Also, any instances of A’s subclasses will inherit from B. See Figures 2.1a 
and 2.1b. 

If a class is replaced multiple times, unique classes specified in 
pszNewClassName for each call to WinReplaceObjectClass will be 
added to the class replacement hierarchy below the most recent re¬ 
placement. 
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Class replacement is useful for changing the behavior of classes that can 
have only one active instance at a time, such as WPDesktop and the device 
classes. 




RESTRICTIONS/WARNINGS 

e The class specified in pszOldClassName must be the direct parent 
class of pszNewClassName as specified in the class definition file 
(.CSC or .IDL). 

m The system must be rebooted before the class replacement can take 
effect. 

m If you replace a class, you run the risk of changing the behavior of ex¬ 
isting classes created by other applications. Therefore, class replace¬ 
ment should be carefully thought out and only used when there are 
no alternatives. 


• WinSaveObjjeet (Warp only) 


Notifies an object to save its data. 

SYNTAX 

BOOL WinSaveObject (HOBJECT hObject, BOOL fAsync) 

PARAMETERS 

hObject - input 

The object handle of the object to save. Object handles can be ob¬ 
tained by calling WinQueryObject or by saving the handle when it is 
returned by WinCreateObject. 
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fAsync - input 

If set to TRUE, the object will be saved asynchronously and the func¬ 
tion will return immediately. If FALSE, the function will not return un¬ 
til after the object has been saved. 

RETURNS 

TRUE—The object was saved successfully. 

NULLHLANDLE—An error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinQueryObject -17, WinSetObjectData -22, wpSaveDeferred -94, 
wpSavelmmediate -95 

NOTES 

When fAsync is set to TRUE, the system will call wpSaveDeferred to save 
the object. When set to FALSE, the system calls wpSavelmmediate. 

Normally, when WinSetObjectData is called, the object will auto¬ 
matically save its data asynchronously without calling WinSaveObject. 
If, however, immediate saving is desired, call WinSaveObject, passing 
FALSE for fAsync. 


• WinSetObjectData 

Passes setup information to an object. 

SYNTAX 

BOOL WinSetObjectData (HOBJECT hObject, PSZ pszSetupString) 

PARAHETERS 

hObject- input 

The persistent handle of an existing object. Object handles can be ob¬ 
tained by calling WinQueryObject or by saving the handle when it is 
returned by WinCreateObject. 
pszSetupString - input 

The desired settings for the specified object. This parameter is in the 
same format as the pszSetupString parameter for WinCreateObject. A 
setup string is a list of keyname value pairs separated by semicolons 
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which is parsed by the object to set instance data. See Appendix A for the 
list of possible keyname value pairs for the predefined Workplace Shell 
classes. For more information on setup strings, see wpSetup (pg. 63). 

RETURNS 

TRUE—The setup string was successfully passed to the object. 

FALSE—The object was not found or an error occurred. 

OTHER INFO 

Include file: pmwp.h Define: INCL_WINWORKPLACE 

SEE ALSO 

WinCreateObject -9, WinOueryObject -17, wpSaveDeferred -94, 
wpSetup -63 

NOTES 

When WinSetObjectData is called, Workplace Shell passes pszSetupString 
to the object using the wpSetup method and then calls wpSaveDeferred 
to asynchronously save the object’s data. 

WinSetObjectData can be used by programs to communicate with 
objects in the Workplace process without using DSOM. The setup 
string can be used to communicate with objects that override the 
wpSetup method to manipulate this application-defined data. 

RESTRICTIONS 

Currently there is no function for querying the settings of an object. 


REXX Functions 


SysCopyObject (Warp) copies a Workplace object (pg. 24). 
SysCreateObject creates a Workplace object (pg. 25). 
SysCreateShadow (Warp) creates a shadow of a Workplace object 
(Pg- 27). 

SysBeregisterObjectClass deregisters a Workplace class (pg. 28). 
SysBestroyObject deletes a Workplace object (pg. 29). 

SysMoveObject (Warp) moves a Workplace object to another folder 
(pg- 30). 

SysOpenObject (Warp) opens a view of a Workplace object (pg. 31). 





24 


Workplace Shell 


SysOueryClassLIst lists all registered Workplace classes (pg. 32). 
SysRegisterObjectClass registers a Workplace class (pg. 33). 
SysSaveObject (Warp) notifies an object to save its data (pg. 33). 
SysSetObjectBata sets instance data on an object (pg. 34). 


• SysCopyObject REXX (Warp only) 

Copies a Workplace object. 

EQUIVALENT C FUNCTION 

WinCopyObject 

SYNTAX 

result = SysCopyObject ( Object , Destination) 

PARAMETERS 

Object - input 

The object to copy. This can be either the object ID (if it exists and is 
known) or, if the object is a descendant of WPFileSystem, the fully 
qualified path of the file representing the object. 

Destination - input 

The folder location for the new copy. This can be either the object ID 
(if it exists and is known) or the fully qualified path of the directory 
represented by the folder. For example, to create an object on the 
Desktop, Location would be either ‘<WP_DESKTOP> 5 or ‘C:\DESK- 
TOP’ (assuming the Desktop is on the C drive and is called ‘Desktop 5 ). 
See Appendix D for a list of predefined folder object IDs. 

RETURNS 

1—The new copy was successfully created. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample for 
SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinCopyObject -8 
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NOTES 

See WinCopyObject (pg. 8) for more information. 


# SysCreateObJect REXX 


Creates a Workplace object of the specified class. 

EQUIVALENT C FUNCTION 

WinCreateObject 

SYNTAX 

result = SysCreateObject ( ClassName , Title , Location [, SetupString, Flag]) 

PARAMETERS 

ClassName - input 

The name of the class for the new object. This must be a registered 
Workplace Shell class. See the class hierarchy (pg. 2) for the list of pre¬ 
defined Workplace Shell classes. This parameter is case-sensitive. 

Title - input 

The title for the new object. 

Location - input 

The folder location for the new object. This can either be the object ID 
(if it exists and is known) or the fully qualified path of the directory 
represented by the folder. For example, to create an object on the 
Desktop, Location would be either ‘<WP_DESKTOP>’ or ‘C:\DESK- 
TOP’ (assuming the Desktop is on the C drive and is called ‘Desktop’). 
See Appendix D for a list of predefined folder object IDs. 

Setup String - input (optional) 

The initial settings for the new object. A setup string is a list of key¬ 
name value pairs separated by semicolons which is parsed by the object 
for initialization. Omit to use the object’s defaults. See Appendix A for 
the list of possible keyname value pairs for the predefined Workplace 
classes. For more information on setup strings, see wpSetup (pg. 63). 
Flag - input (optional) 

This flag specifies what action should take place if a duplicate existing 
object is found. If an object ID is specified in SetupString and an exist¬ 
ing object with that ID is found or an existing object with the same ti¬ 
tle in the same folder is found, that object is considered a duplicate. 
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Valye 

Action 

‘Fail’ 

If a duplicate is found, the new object is not created and the 
call will fail. 

‘Replace’ 

If a duplicate is found, the new object is created and replaces 
the duplicate. 

‘Update’ 

If a duplicate is found, the new object is not created and, 
if specified, SetupString is passed to the duplicate as if 
SysSetObjectData were called. 


Only the first letter of the flag is required. The rest are ignored. 


RETURNS 

1—The object was successfully created. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample code.) 

SEE ALSO 

SysDestroyObject -29, SysRegisterObjectClass -33, SysSetObjectData -34, 
WinCreateObject -9 

NOTES 

SysCreateObject does not return an object handle. The REXX 
Workplace functions use object IDs only to identify objects. 

See WinCreateObject (pg. 9) for more information. 

SAMPLE CODE 

/* Load the REXX utility function */ 

call RxFuncAdd 'SysCreateObject', 'RexxUtil', 'SysCreateObject' 


/* create a folder object on the Desktop named 'My Folder' that is 
not deleteable and assign it the object ID, <MY_FOLDER>. Specify 
'Fail' as the last parameter so a duplicate will not be created. 

*/ 

result = SysCreateObject ('WPFolder',, /* class name */ 

'My Folder',, /* title */ 

'<WP_DESKTOP>',, 
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'NODELETE=YES;OBJECTID=<MY_FOLDER >', , 
'Fail 7 ) 

if result = 1 then 

say 'My Folder created successfully' 
else 

say 'My Folder not created successfully' 


• SysCreateShadow REXX (Warp only) 


Creates a shadow of a Workplace object. 

EQUIVALENT C FUNCTION 

WinCreateShadow 

SYNTAX 

result = SysCreateShadow ( Object, Destination) 

PARAMETERS 

Object - input 

The object to be shadowed. This can be either the object ID (if it exists 
and is known) or, if the object is a descendant of WPFileSystem, the 
fully qualified path of the file representing the object. 

Destination - input 

The folder location for the new shadow. This can be either the object 
ID (if it exists and is known) or the fully qualified path of the directory 
represented by the folder. For example, to create an object on the 
Desktop, Location would either be ‘<WP_DESKTOP>’ or ‘C:\DESK- 
TOP’ (assuming the Desktop is on the C drive and is called ‘Desktop’). 
See Appendix D for a list of predefined folder object IDs. 

RETURNS 

1—The new shadow was successfully created. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 
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The function must be loaded before it can be called. (See sample for 
SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinCreateShadow -11 

NOTES 

See WinCreateShadow (pg. 11) for more information. 


• SysDeregisterObjectClass REXX 

Deregisters a Workplace class. 

EQUIVALENT C FUNCTION 

WinDeregisterObjectClass 

SYNTAX 

result = SysDeregisterObjectClass ( ClassName) 

PARAMETERS 

ClassName - input 

The name of the class to deregister. Predefined Workplace classes can¬ 
not be deregistered. This parameter is case-sensitive. 

RETURNS 

1—The class deregistered successfully. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample for 
SysCreateObject, pg. 25.) 

SEE ALSO 

WinDeregisterObjectClass -12, SysDestroyObject -29, 
SysRegisterObjectClass -33, SysQueryClassList -32 
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NOTES 

See WinDeregisterObjectClass (pg. 12) for more information. 


• SysDestroyObJect REXX 


Deletes a Workplace object. 

EQUIVALENT C FUNCTION 

WinBestroyObject 

SYNTAX 

result = SysDestroyObject ( Object ) 

PARAMETERS 

Object- input 

The Object ID or, if the object is a descendant of WPFileSystem, the fully 
qualified path of any object. If the object is OBJSTYLE_NODELETE, 
SysDestroyObject will still try to delete it. See Appendix D for a list of ob¬ 
ject IDs of the predefined Workplace Shell objects. 

RETURNS 

1—The object was successfully deleted. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. The function must be loaded before it 
can be called. (See sample code for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinBestroyObject -13 
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@ SysMoveObject RBXX (Warp only) 

Moves a Workplace object to another folder. 

EQUIVALENT C FUNCTION 

WinMoveObject 

SYNTAX 

result = SysMoveObject (Object, Destination) 

PARAMETERS 

Object - input 

The object to move. This can be either the object ID (if it exists and is 
known) or, if the object is a descendant of WPFileSystem, the fully 
qualified path of the file representing the object. 

Destination - input 

The new folder location for the specified object. This can be either the 
object ID (if it exists and is known) or the fully qualified path of the di¬ 
rectory represented by the folder. For example, to create an object on 
the Desktop, Location would be either ‘<WP_DESKTOP>’ or ‘C:\DESK- 
TOP’ (assuming the Desktop is on the C drive and is called ‘Desktop’). 
See Appendix D for a list of predefined folder object IDs. 

RETURNS 

1—The object was moved successfully. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. The function must be loaded before it 
can be called. (See sample for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinMoveObject -16 

NOTES 

See WinMoveObject (pg. 16) for more information. 
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# SysOperiObJect REXX (Warp only) 

Opens a view of a Workplace object. 

EQUIVALENT C FUNCTION 

WinOpenObject 

SYNTAX 

result = SysOpenObject ( Object , View , FYagj 

PARAMETERS 

Object - input 

The object to open. This can be either the object ID (if it exists and is 
known) or, if the object is a descendant of WPFileSystem, the fully 
qualified path of the file representing the object. 

View - input 

The value representing the view to open for this object. For example, 
to open the settings view, View should be 2, which corresponds to 
OPEN_SETTINGS. See Appendix E for a list of predefined Workplace 
views. 

Flag - input 

When set to ‘True’, the view will be opened following the window open 
behavior of the object. If the object does not support concurrent views 
and the view specified is already opened, the existing view will be sur¬ 
faced. When set to ‘False’, a new view will always be opened. 

RETURNS 

1—The view was opened successfully. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample code 
for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinOpenObject -16 

NOTES 

See WinOpenObject (pg. 16) for more information. 
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® SysQueryClassList REXX 

Enumerates all registered Workplace classes. 

EQUIVALENT C FUNCTION 

WinEnumObjectClasses 

SYNTAX 

result = SysQueryClassList (‘ List .’) 

PARAMETERS 

List - output 

Name of a stem variable. The class list will be placed in the specified 
stem starting with List. 1. List.O will contain the total number of entries. 

RETURNS 

1—The call was successful. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample code.) 

SEE ALSO 

SysDeregisterObjectClass -28, SysRegisterObjectClass -33, 
WinEnumObjectClasses -14 

SAMPLE CODE 

/* Load the REXX utility function */ 

call RxFuncAdd 'SysQueryClassList', 'RexxUtil', 'SysQueryClassList' 

/* Store the class list in a stem variable called ClassList and 
output to screen*/ 

result = SysQueryClassList ('ClassList.') 
if result = 1 then 

say 'Workplace Classes' 

say '-' 

do count = 1 to ClassList.0 
say ClassList.count 

else 

say 'SysQueryClassList failed. 
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® SysRegisterObJectClass REXX 

Registers a Workplace class. 

EQUIVALENT C FUNCTION 

WinRegisterObjectClass 

SYNTAX 

result = SysRegisterObjectClass ( ClassName , ModuleName) 

PARAMETERS 

ClassName - input 

The name of the class to register. The parameter is case-sensitive, and 
the name of the class must be unique in the system. 

ModuleName - input 

The name of the DLL with the class definition. 

RETURNS 

1—The class registered successfully. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample code 
for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, SysDeregisterObjectClass -28, 

SysOueryClassList -32, WinRegisterObjectClass -18 

NOTES 

For more information, see WinRegisterObjectClass (pg. 18). 


® SysSaveObjjeet REXX (Warp only) 


Notifies an object to save its data. 
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EQUIVALENT C FUNCTION 

WinSaveObject 

SYNTAX 

result = SysSaveObject ( Object , Async) 

PARAHETERS 

Object - input 

The object to save. This can be either the object ID (if it exists and is 
known) or, if the object is a descendant of WPFileSystem, the fully 
qualified path of the file representing the object. 

Async - input 

If set to ‘True’, the object will be saved asynchronously and the func¬ 
tion will return immediately. If ‘False’, the function will not return un¬ 
til after the object has been saved. 

RETURNS 

1—The object was saved successfully. 

0—An error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. The function must be loaded before it 
can be called. (See sample for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinSaveObject -21 

NOTES 

See WinSaveObject (pg. 21) for more information. 


0 SysSetObJectBata REXX 

Passes setup information to an object. 

EQUIVALENT C FUNCTION 

WinSetObjectData 
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SYNTAX 

result = SysSetObjectData ( Object , SetupString) 

PARAMETERS 

Object- input 

The object ID or, if the object is a descendant of WPFileSystem, the 
fully qualified path of any existing object. Object IDs can be specified 
in the SetupString parameter of SysCreateObject. See Appendix D for 
a list of object IDs of the predefined Workplace objects. 

SetupString - input 

The desired settings for the specified object. This parameter is in the 
same format as the SetupString parameter for SysCreateObject. A 
setup string is a list of keyname value pairs separated by semicolons 
which is parsed by the object to set instance data. See Appendix D for 
the list of possible keyname value pairs for the predefined Workplace 
Shell classes. For more information on setup strings, see wpSetup 
(pg. 63). 

RETURNS 

1—The setup string was successfully passed to the object. 

0—The object was not found or an error occurred. 

OTHER INFO 

The REXX Workplace functions are contained in REXXUTIL.DLL 
which must be in the LIBPATH. 

The function must be loaded before it can be called. (See sample code 
for SysCreateObject, pg. 25.) 

SEE ALSO 

SysCreateObject -25, WinSetObjectData -22, wpSetup -63 
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Installing Workplace Classes: Structures 


OBJCLASS 




-____ 


Ml 


' 

_ 



pNext (POBJCLASS) 0 

is the pointer to the next OBJCLASS node in the list. If pNext is NULL, this node is last in 
the linked list. 

pszClassName (PSZ) 4 

is a string containing the name of the class. 

pszModName (PSZ) 8 

is a string containing the name of the DLL in which this class is defined. This name will only 
be fully qualified if WinRegisterObjectClass was called with a fully qualified module name 
for this class. 

Used by: WinEnumObjectClasses -14 





T his chapter describes the object manipulation methods that are 
defined by WPObject and, therefore, are inherited by all Work¬ 
place subclasses. These methods may be called by the system or the 
programmer to create, move, copy, and delete objects. 
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To conserve memory usage, persistent objects (descendants of ei¬ 
ther WPFileSystem or WPAbstract) that are not currently in use ei¬ 
ther by the user or an application are not loaded in memory. When 
an object is in memory, it is said to be awake; otherwise, it is dor¬ 
mant. Objects are awakened by the system when they are created or 
when they come into use and are not yet in memory. Some exam¬ 
ples of when an object comes into use are: a view of the object is 
opened, a view of the parent folder is opened, a shadow of the ob¬ 
ject is awakened, or the object is a folder and a contained object is 
awakened. An object can also be awakened by an application with 
wpclsOueryObject or wpclsObjectFromHandle (Warp). 

The Instance Lock Count 

The Workplace Shell maintains a lock count for each object in the sys¬ 
tem to keep track of whether the object is in use or must be made dor¬ 
mant. The system automatically increments the lock count for an ob¬ 
ject (that is, locks the object) each time it is used by the system and 
decrements the lock count (that is, unlocks the object) when it is no 
longer needed for that particular usage. For example, since an object 
can have several views open simultaneously, each time a view is 
opened, the system locks the object, and as each view is closed, the sys¬ 
tem unlocks the object. 

When the lock count for an object is decremented to zero, 
Workplace puts the object in a list of objects that must be made dor¬ 
mant. Every 90 seconds a thread in Workplace goes through the list 
and makes each object dormant. This timeout value is configurable in 
the CONFIG.SYS by adding the line 

SET OBJECTSNOOZETIME = n 

where n is the number of seconds for the timeout. Application devel¬ 
opers may want to lower this value on their test machines to force ob¬ 
jects to go dormant sooner than 90 seconds. This is advantageous be¬ 
cause while objects of a class are awake, the class definition .DLL is in 
use and cannot be replaced with a newer version. One way to replace 
the .DLL is to force all instances to go dormant by closing them and 
placing them in a closed folder and then waiting for the snooze time to 
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Since descendants of WPTransient are not persistent, their lock 
count is ignored and they are never made dormant. To release a tran¬ 
sient object from memory, call wpFree to destroy it. If an object were to 
go dormant while an application is manipulating the object (calling 
methods on the object), a trap in Workplace would occur. To avoid 
this, all methods that return an object pointer will lock the object be¬ 
fore returning, either automatically or at the programmer’s discretion 
through the use of an fLock parameter. It is the responsibility of the 
programmer to call wpUnlockObject when the object is no longer 
needed by the application. In Warp, the programmer can use 
wpLockObject to place additional locks on an object to ensure that it 
will remain awake. 

Restrictions and Warnings 

® It is not guaranteed that a method will be called whenever an object 
is created, deleted, or moved. Sometimes, Workplace will manipu¬ 
late an object without calling these methods. For example, if a 
folder is copied or moved, public methods are not called to copy or 
move its contents. 

® Workplace uses a dialog for copy, move, create another, and create 
shadow actions selected from the pop-up menu. There is no pro¬ 
gramming interface to use or modify these dialogs. 

® The method wpLockObject was not made public until Warp. OS/2 
2.1 applications can lock an object by first calling wpQueryHandle 
and then wpclsQueryObject. 

® Be aware that dereferencing a SOM pointer for an object that has 
gone dormant will cause a trap. Methods that lock objects will be 
documented as such in this reference. Until you unlock the object, 
it is safe to access the SOM pointer. If you pass an object pointer to 
a function that runs asynchronously, be sure that you lock the object 
or that you only access the SOM pointer when you know the object 
must still be awake. 

® In version 2.1, if wpCreateFromTemplate is called on a template ob¬ 
ject with an object ID, it will copy the object ID to the new object. 
This is bad because object IDs must be unique among objects; this 
bug was fixed in Warp. The workaround in 2.1 would be to avoid 
placing object IDs on template objects or to override 
wpCopiedFromTemplate to reset the object ID to a blank string (by 
calling wpSetup on the new object and passing “OBJECT= ” as the 
setup string). 
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Instance Methods 


wpConfirmDelete prompts the user for confirmation on the deletion 
of an object (pg. 40). 

wpCopiedFromTemplate notifies an object that it has been copied 
from a template (pg. 43). 

wpCopyObject copies an object to the specified folder (pg. 44). 
wpCreateAnother creates another object of the same class (pg. 47). 
wpCreateFromTempIate creates a new object from a template 
(pg. 48). 

wpCreateShadowObject creates a shadow of an object in the specified 
folder (pg. 50). 

wpDelete deletes an object using the specified confirmations 
(pg. 51). 

wpFree deletes an object regardless of the object’s style (pg. 53). 
wpIsDeleteable (Warp) tests if an object can be deleted (pg. 54). 
wpIsLocked (Warp) tests if an object is locked (pg. 55). 
wpIsObjectlnitialized (Warp) tests if an object is fully initialized 
(pg. 56). 

wpLockObject (Warp) increments an object’s lock count by one 
(pg. 56). 

wpMoveObject moves an object to the specified folder (pg. 57). 
wpObjectReady (Warp) notifies an object when it becomes completely 
initialized (pg. 58). 

wpQueryHandle returns the handle of an object (pg. 60). 
wpScanSetupString parses a setup string (pg. 61). 
wpSetup sets or changes the settings of an object (pg. 63). 
wpSetupOnce (Warp) sets the settings of an object when it is first cre¬ 
ated (pg. 64). 

wpUnlockObject reduces an object’s lock count by one (pg. 65). 


# wpConfirmDelete WPObject instance method 

Prompts the user for confirmation on the deletion of an object. 

SYNTAX 

ULONG wpConfirmDelete (ULONG /Confirmations) 
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PARAMETERS 

/Confirmations - input 

Any combination of the following flags ORed together: 


Constant 


Defined Name 

CONFIRM_DELETE 

0x01 

Confirm deletion of all objects. 

CONFIRM JDELETEFOLDER 

0x02 

Confirm deletion of folders. 

RETURNS 

Define 


Defined Name 

OKJDELETE 

1 

The object can be deleted. 

NO_DELETE 

2 

The object cannot be deleted. 

CAN CEL_DELETE 

3 

The user canceled the entire 
delete operation. 


HOWTO CALL 

Call this method on any object to confirm its deletion. The user will be 
prompted with a message box asking for confirmation to delete an object 
or an entire folder, depending upon the confirmation flags specified. 

HOWTO OVERRIDE 

Override this method to change its behavior. Prompt the user for con¬ 
firmations and return one of the valid *_DELETE codes (see above) 
without calling the parent method, or call the parent method to have 
the system put up the message box confirming the deletion. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpDelete -51, wpFree -53, wpIsDeleteable -54, 
wpQueryConfirmations -111 

NOTES 

If you are deleting many objects and wpConfirmDelete returns CAN- 
CEL_DELETE, cancel the entire delete operation and do not delete 
any more objects. If NOJDELETE is returned, do not delete the one 
object but continue with the others. 
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RESTRICTIONS/WARNINGS 

• If you are overriding wpConfirmDelete, note that the f Confirmations 
parameter could contain other flags that are unrelated to deletion. 
Do not test fConfirmations for zero to determine if 
CONFIRM_DELETE and/or CONFIRM_DELETEFOLDER are 
present. 

@ When the system deletes an object as a result of the user selecting 
“Delete” from the pop-up menu, a special confirmation dialog is 
presented to the user, and wpDelete is called on each object with 
fConfirmations set to zero. In this case, wpConfirmDelete is not 
called. However, when the system deletes an object as a result of the 
user pressing the Delete key on the keyboard, wpDelete is called 
with /Confirmations set to CONFIRMJDELETEFOLDER if the object 
is a folder, and CONFIRM_DELETE otherwise. In this case, 
wpConfirmDelete is called. 

SAMPLE CODE 

The following sample obtains an object pointer for a folder using its 
object ID and deletes it using wpConfirmDelete. The context of this 
sample could be within a method or a regular function. 

SOMAny *Object; 

ULONG ulAnswer; 

BOOL bSuccess = FALSE; 

/* Wake up a folder with the object ID, <MY_FOLDER> and delete it */ 
Object = _wpclsQueryFolder (_WPObject, "<MY_FOLDER>", TRUE); 
if (Object) 

{ 

/* Confirm deletion from the user but pass the default 

confirmation flags with wpQueryConfirmations to get the user 
delete confirmation preferences from the system object. 
wpConfirmDelete will only look at the flags that involve 
object deletion. 

*/ 

ulAnswer = _wpConfirmDelete(Object, _wpQueryConfirmations(Object)); 
if (ulAnswer == OK_DELETE) 

{ 

/* we can call wpFree instead of wpDelete because we already 
handled the 
* confirmations. 

*/ 
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bSuccess = _wpFree(Object); 

} 

if (!bSuccess) 

{ 

/* the deletion was not successful. Unlock the object so it can 
go dormant*/ 

_wpUnlockObject(Object); 


} 


® wpCopiedFromTempIate WPObject instance method 


Notifies an object that has been copied from a template. 

SYNTAX 

VOID wpCopiedFromTempIate ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method is generally called only by the system on a new object af¬ 
ter it has been copied from a template. 

HOWTO OVERRIDE 

Override this method to perform any necessary processing or initial¬ 
ization once a new object has been copied from a template. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsNew -71, wpclsQueryStyle -127, wpCopyObject -44, 
wpCreateFromTemplate -48, wpModifyStyle -108, wpObjectReady -58 
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NOTES 

An object is copied from a template when the user drags from a tem¬ 
plate object or selects a template name from the Create Another pull¬ 
down in a pop-up menu. Workplace Shell calls the wpCreateFrom- 
Template method to create the new object and then on the new object 
for notification. Neither wpCopyObject nor wpclsNew is called. The 
new object is an exact copy of the template, except that the OBJ- 
STYLE JTEMPLATE and OBJSTYLE_NODELETE styles are removed. 

RESTRICTIONS/WARNINGS 

• If your class style is CLSSTYLE_NEVERDELETE, wpCreateFrom- 
Template will still remove the OBJSTYLE_NODELETE flag from the 
new object. Override wpCopiedFromTemplate to put the OBJ- 
STYLE_NODELETE style back on the new object (see sample below). 
9 wpObjectReady (Warp) can also be overridden for notification when 
an object has been created from a template. 

SAMPLE CODE 

The following sample is an override of the wpCreateFromTemplate 
method for a class called ProtectedClass. The default style of this class 
includes CLSSTYLE_NEVERDELETE. wpCreateFromTemplate is 
overridden to put the OBJSTYLE_NODELETE flag on the new object. 

SOM_Scope void SOMLINK pcls_wpCopiedFromTemplate 
(ProtectedClass *somSelf) 

{ 

/* put the OBJSTYLE_NODELETE style back on the object */ 
_wpModifyStyle(somSelf, OBJSTYLE_NODELETE, OBJSTYLE_NODELETE); 

/* mark the object to save its data */ 

_wpSaveDeferred(somSelf); 
parent_wpCopiedFromTemplate(somSelf); 

} 


@ wpCopyObject WPObject instance method 

Copies an object to the specified folder. 

SYNTAX 

WPObject * wpCopyObject (WPFolder * Folder, BOOL fLock) 



Object Manipulation 


45 


PARAMETERS 

Folder —input 

The object pointer of the folder in which to place the newly copied ob¬ 
ject. Some methods for obtaining Folder object pointers are wpcls- 
QueryFolder, wpclsQueryObject, and wpclsQueryObjectFromPath. 
fLock —input 

TRUE—Increment the lock count on the new object returned. 

FALSE—Do not increment the lock count on the new object. 

RETURNS 

(nonzero value)—The object pointer for the new copy of the object. 
NULL—An error occurred. 

HOWTO CALL 

Call this method on any object to make an exact copy. The storage 
class will copy all the persistent instance data of the original and save it 
in the copy. The object ID and object handle of the original, if they ex¬ 
ist, will not be copied to the new object. 

HOWTO OVERRIDE 

Override this method for notification when an object is being copied. 
Call the parent method to do the actual copy and be sure to return the 
new object from your override. If the parent method is not called, the 
object will not be copied properly. See the sample code for an example 
of overriding this method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpCreateFromTemplate -48, wpCreateAnother -47, wpclsNew -71, 
wpclsObjectFromHandle -72, wpclsOueryFolder -74, 
wpclsQueryObject -75, wpclsQueryObjectFromPath -76, 
wpMoveObject -57, wpObjectReady -58, wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

• Pass TRUE for fLock if you are going to use the returned object 
pointer when calling wpCopyObject. Otherwise, the object might be 
freed before you are finished with the pointer. Be sure to call 
wpUnlockObject when the pointer is no longer needed. 



46 


Workplace Shell 


• If you are overriding the method to manipulate the new copy and 
the caller specified FALSE for fLock, pass TRUE to the parent 
method and then call wpUnlockObject on the new object when you 
are finished (see sample below). 

$ When an object is copied, the storage classes use the save and re¬ 
store methods to copy the data from one object to another. This 
means that any data that is not saved and restored in the 
wpSaveState and wpRestoreState methods will not get copied. In the 
case of WPTransient descendants, no data will be copied because 
WPTransient does not process the save and restore methods. 
Override wpCopyObject to copy any data that would not be copied 
by the storage class. 

# If there is persistent instance data defined by your class that is 
unique for each object or would not make sense to be copied over 
to the new object, override wpCopyObject and change the data after 
calling the parent method (see sample below). 

© wpCopyObject is not always called on an object when it is copied by 
the system. If a folder is copied, wpCopyObject will not be called on 
the folder’s contents. 

m wpObjectReady (Warp) can also be overridden for notification 
when an object is copied. 

SAMPLE CODE 

The following sample demonstrates how to override wpCopyObject to 
perform an action on the new copy. In this case, the action will be to 
call the method SetUniqueData on the object to reset a persistent in¬ 
stance variable to zero. (SetUniqueData is assumed to be defined for 
this class and is not shown here.) The name of the class in this exam¬ 
ple is MyClass. 

SOM_Scope WPObject * SOMLINK mycls_wpCopyObject (MyClass *301118011, 

WPFolder *Folder, 

BOOL fLock) 

{ 

SOMAny *NewObject; 

/* First call the parent method to perform the copy. Pass TRUE for 
fLock */ 

NewObject = parent_wpCopyObject(somSelf, Folder, TRUE); 

/* reset the data */ 

_SetUniqueData(NewObject, 0 ); 
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/* mark the object to save its data */ 

_wpSaveDeferred(NewObject); 

/* if the caller had not specified to lock the object, unlock it 
*/ 

if (!fLock) 

_wpUnlockObject(NewObject); 
return(NewObject); 


® wpCreateAnother WPObject instance method 

Creates another object of the same class. 

SYNTAX 

WPObject * wpCreateAnother (PSZ pszTitle, PSZ pszSetupEnv, 

WPFolder * Folder ) 


PARAMETERS 

pszTitle - input 

The title for the new object. 

pszSetupEnv - input 

The initial settings for the new object. A setup string is a list of key¬ 
name value pairs separated by semicolons which is parsed by the object 
for initialization. Specify NULL to use the object’s defaults. See 
Appendix A for the list of possible keyname value pairs for the prede¬ 
fined Workplace Shell classes. For more information on setup strings, 
seewpSetup (pg. 63). 

Folder - input 

The object pointer of the folder in which to place the newly created 
object. Some methods for obtaining Folder object pointers are wpcls- 
QueryFolder, wpclsQueryObject, and wpclsQueryObjectFromPath. 

RETURNS 

(nonzero value)—The object pointer for the new object. 

NULL—An error occurred. 
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HOWTO CALL 

Call this method on any object to create a new object of the same class. 

HOWTO OVERRIDE 

Override this method for notification when the user chooses the de¬ 
fault Create another pop-up menu item from an object. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsNew -71, wpclsObjectFromHandle -72, wpclsQueryFolder -74, 
wpclsQueryObject -75, wpclsQueryObjectFromPath -76, 
wpObjectReady -58, wpSetup -63, wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

• The WPObject class handles this method by querying the class of 
the object and calling wpclsNew with the same parameters. The 
JLock parameter is passed as TRUE to wpclsNew, therefore the re¬ 
turned new object will be locked and must be unlocked with 
wpUnlockObject when its pointer is no longer needed. 

• This method is predominantly useful to override for notification. 
Calling wpclsNew directly is more flexible and can be used instead 
to create new objects. 

© wpCreateAnother is only called by the system when the user chooses 
the default Create another item in the pop-up menu of an object. 
wpclsNew is called directly when WinCreateObject is called from an 
application or when the system creates objects. 

® wpObjectReady (Warp) can be overridden instead for notification 
of creation of a new object. 


9 wpCreateFromTempfate WPObject 

Instance method 


Creates a new object from a template. 

SYNTAX 

WPObject * wpCreateFromTemplate (WPFolder * folder, BOOL fLock) 
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PARAMETERS 

folder - input 

The object pointer of the folder in which to place the newly created 
object. Some methods for obtaining folder object pointers are wpcls- 
QueryFolder, wpclsQueryObject, and wpclsQueryObjectFromPath. 
fLock - input 

TRUE—Increment the lock count on the new object returned. 

FALSE—Do not increment the lock count on the new object. 

RETURNS 

(nonzero value)—The object pointer for the new object. 

NULL—An error occurred. 

HOWTO CALL 

Call this method on any template to create a new object. A template is 
an object with the style OBJSTYLE TEMPLATE. 

HOWTO OVERRIDE 

This method does not need to be overridden for notification purposes 
because wpCopiedFromTemplate and wpObjectReady (Warp) will be 
invoked on the newly created object. The returned object will have the 
same settings as the original template except the OBJSTYLE_NO- 
DELETE, if present, and OBJSTYLE_TEMPLATE styles are removed. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsNew -71, wpclsOueryFolder -74, wpclsQueryObject -75, 
wpclsQueryObjectFromPath -76, wpCopiedFromTemplate -43, 
wpModifyStyle -108, wpObjectReady -58, wpSetup -63, 
wpUnlockObject -65 

NOTES 

An object is copied from a template when the user drags from a 
template object or selects a template name from the Create another 
pulldown in a pop-up menu. Workplace Shell calls the wpCreate- 
FromTemplate method to create the new object and then wpCopied¬ 
FromTemplate on the new object for notification. Neither wpCopy- 
Object nor wpclsNew is called. The new object is an exact copy of the 
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template except the OBJSTYLE_TEMPLATE and OBJSTYLE_- 

NODELETE styles are removed. 

RESTRICTIONS/WARNINGS 

# If your class style is CLSSTYLENEVERDELETE, wpCreateFrom- 
Template will still remove the OBJSTYLE_NODELETE flag from 
the new object. Override wpCreateFromTemplate or wpObject- 
Ready (Warp) to put the OBJSTYLEJNfODELETE style back on the 
new object. 

# Pass TRUE for the fLock parameter if you are going to access the ob¬ 
ject pointer after calling wpCreateFromTemplate. When the pointer 
is no longer needed, call wpUnlockObject. 

# In version 2.1, if wpCreateFromTemplate is called on a template ob¬ 
ject with an object ID, it will copy the object ID to the new object. 
This is bad because object IDs must be unique among objects; this 
bug was fixed in Warp. The workaround in 2.1 would be to avoid 
placing object IDs on template objects or to override wpCopied- 
FromTemplate to reset the object ID to a blank string (by calling 
wpSetup on the new object and passing “OBJECT^ ” as the setup 
string). 


• wpCreateShadowObjeet WPObject 

instance method 


Creates a shadow of an object in the specified folder. 

SYNTAX 

WPObject * wpCreateShadowObjeet (WPFolder * Folder .; BOOL /Lock) 

PARAMETERS 

Foldei - - input 

The object pointer of the folder in which to place the shadow. Some 
methods for obtaining Folder object pointers are wpclsOueryFolder, 
wpclsOueryObject, and wpclsOueryObjectFromPath. 
fLock - input 

TRUE—Increment the lock count on the new shadow object returned. 
FALSE—Do not increment the lock count on the new shadow object. 
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RETURNS 

(nonzero value)—The object pointer for the new object. 

NULL—An error occurred. 

HOWTO CALL 

Call this method on any object to create a shadow of the object. A US- 
AGE LINK item will be added to the in-use list of the original object. 
See Chapter 15 for more information on shadows and Chapter 6 for 
more information on in-use lists. 

HOWTO OVERRIDE 

This method can be overridden for notification when a user creates a 
shadow of an object by using Ctrl+Shift+Drag or selecting Create 
shadow from the pop-up menu. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAddToObjUseList -145, wpclsQueryFolder -74, 
wpclsQueryObject -75, wpclsQueryObjectFromPath -76, 
wpQueryShadowedObject -298, wpUnlockObject -65 

NOTES 

Pass TRUE for the /Lock parameter if you are going to access the 
shadow object pointer after calling wpCreateShadowObject. When the 
pointer is no longer needed, call wpUnlockObject. 


© wpDeiete WPObject instance method 


Deletes an object using the specified confirmations. 

SYNTAX 

ULONG wpDeiete (ULONG fConfirmations) 

PARAMETERS 

/Confirmations - input 

Specify 0 for no user confirmation or any combination of the following 
flags ORed together: 
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Constant Description 

CONFIRM_BELETE 0x01 Confirm deletion of all objects. 

CONFIRM_DELETEFOLDER 0x02 Confirm deletion of folders. 

RETURNS 

Constant Description 

OK_DELEE 1 The object was deleted. 

NO_DELETE 2 An error occurred or the user 

specified No at the prompt. 

CANCEL_DELETE 3 The user canceled the delete 

operation. 

HOWTO CALL 

Call this method on any object to delete it. The WPObject class will 
first make sure the object does not have the style ORJSTYLE_- 
NOBELETE. Then it calls wpConfirmDelete if delete confirmation 
flags are passed in. If wpConfirmDelete returns OK DELETE, wpFree 
is called to delete the object. 

HOWTO OVERRIDE 

This method can be overridden to do special processing when an ob¬ 
ject is deleted, but wpDelete is not always called by the system to delete 
an object. It is better to override wpFree for this purpose. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinDestroyObject -13, wpConfirmDelete -40, wpDeleteContents -236, 
wpFree -53, wpIsDeleteable -54, wpQueryConfirmations -111 

RESTRICTIONS/WARNINGS 

# Before calling wpDelete, you should call wpQueryConfirmations 
on the object to determine which flags to pass in the /Confirmations 
parameter. 

# Do not call wpDelete on the somSelf pointer from within an instance 
method override. The object and its SOM pointer will be destroyed 
before the method returns. Any code that subsequently accesses that 
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pointer either from the override itself or from the caller of the 
method will trap. One way an object can delete itself would be to post 
a message to an application-defined thread to do the deletion. 

® WPFolder overrides wpDelete to delete its contents with wpDelete- 
Contents before calling the parent method to delete the folder ob¬ 
ject itself. 

# If wpDelete is called on a folder containing many objects, it should 
be done from a separate thread to avoid temporarily hanging the 
user interface. 

o When the system deletes an object as a result of the user selecting 
Delete from the pop-up menu, a special confirmation dialog is pre¬ 
sented to the user, and wpDelete is called on each object with 
fConfirmations set to zero. In this case, wpConfirmDelete is not 
called. However, when the system deletes an object as a result of the 
user pressing the Delete key on the keyboard, wpDelete is called 
with /Confirmations set to CONFIRM_DELETEFOLDER if the object 
is a folder, and CONFIRM_DELETE otherwise. In this case, 
wpConfirmDelete is called. 


# wpFree WPObJect instance method 

Deletes an object. 

SYNTAX 

BOOL wpFree ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The object was successfully deleted. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to delete it. If user confirmation from 
the user is desired, call the wpDelete method instead. 

HOWTO OVERRIDE 

This method can be overridden to do special processing when an ob¬ 
ject is deleted. 




54 


Workplace Shell 


OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinDestroyObject -12, wpConfirmDelete -40, wpDelete -51, 

wpDeleteContents -236, wpIsDeleteable -54, 

wpQueryConfirmations -111 

RESTRICTIONS/WARNINGS 

• Do not call wpFree on the somSelf pointer from within an instance 
method override. The object and its SOM pointer will be destroyed 
before the method returns. Any subsequent code that accesses that 
pointer either from the override itself or from the caller of the 
method will trap. One way an object can delete itself would be to 
post a message to an application-defined thread to do the deletion. 

® If wpFree is called on a folder containing many objects, it should be 
done from a separate thread to avoid temporarily hanging the user 
interface. 

• WPFolder overrides wpFree and deletes its contents with wpDelete¬ 
Contents before calling the parent method to delete the folder ob¬ 
ject itself. 


• wpIsDeleteable WPObJeet instance method 

(Warp only) 


Tests if an object can be deleted. 

SYNTAX 

BOOL wpIsDeleteable ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The object can be deleted. 

FALSE—The object cannot be deleted. 

HOWTO CALL 

Call this method on any object to determine if it can be deleted by the 
user. Although any object can be deleted using wpFree, this method is 
useful in determining if an object is meant to be deleted. 


Object Manipulation 


55 


HOWTO OVERRIDE 

This method can be overridden to do special processing to determine 
if an object can be deleted. 

OTHER INFO 

Include file: wpobjecth 

SEE ALSO 

wpConfirmDelete -40, wpDelete -51, wpDeleteContents -236, 
wpFree -53, wpQueryConfirmations -111 


® wpIsLocked WPObject instance method (Warp only) 

Tests if an object is locked. 

SYNTAX 

BOOL wpIsLocked ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The object is locked. 

FALSE—The object is not locked. 

HOWTO CALL 

Call this method on any object to determine if it is locked. If an ob¬ 
ject’s lock count is greater than zero, it is considered locked and can¬ 
not be made dormant. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 


SEE ALSO 

wpLockObject -56, wpUnlockObject -65 
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# wpfsObjectlnitiaiized WPObfect Instance method 
__(Warp only)_ 


Tests if an object is initialized. 

SYNTAX 

BOOL wpIsObjectlnidalized ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The object is fully initialized. 

FALSE—The object is not initialized. 

HOWTO CALL 

When an object is created or awakened, it goes through an initializa¬ 
tion process. Until this process is complete, the object is not consid¬ 
ered initialized and certain methods, such as wpSaveDeferred, have no 
effect. wpIsObjectlnidalized can be called at any time to determine 
whether the initialization process is complete. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpObjectReady -58 


• wpLockObject WPObject Instance method (Warp only) 


Increments an object’s lock count by one. 

SYNTAX 

BOOL wpLockObject ( ) 




Object Manipulation 


57 


PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to increment its lock count by one. As 
long as the lock count of an object is nonzero, it will not be made dor¬ 
mant by the system. If an object is referenced in asynchronous pro¬ 
cessing, call wpLockObject before using the object and then wpUn- 
lockObject when it is no longer needed. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject. 

SEE ALSO 

wpUnlockObject -65 

NOTES 

The lock count is an internal counter the WPObject class defines to 
keep track of whether an object is needed in memory. The system will 
increment the lock count of an object once for every open view in the 
in-use list, once for every open folder view in which the object is con¬ 
tained, once for every shadow of the object, once for every contained 
object if the object is a folder, and once every time a method is called 
with the fLock parameter set to TRUE. It is the application’s responsi¬ 
bility to call wpUnlockObject after locking an object. 


# wpMoveObJect WPObject instance method 


Moves an object to the specified folder. 

SYNTAX 

BOOL wpMoveObject (WPFolder *Folder ) 
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PARAMETERS 

Folder - input 

The pointer of the new folder location for the object. Some methods 
for obtaining Folder object pointers are wpclsQueryFolder, 
wpclsQueryObject, and wpclsQueryObjectFromPath. 

RETURNS 

TRUE—The object was successfully moved. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to move it to another folder. 

HOWTO OVERRIDE 

Override this method for notification when an object is being moved. 
Call the parent method to do the actual move. If the parent method is 
not called, the object will not be moved properly. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryFolder -74, wpclsQueryObject -75, 
wpclsQueryObjectFromPath -76, wpCopyObject -44 

RESTRICTIONS/WARNINGS 

• wpMoveObject is not always called on an object when it is moved by 
the system. If a folder is moved, wpMoveObject will not be called on 
the folder’s contents. 


• wpObjectReady WPObject instance method 

(Warp only) 

Notifies an object when it becomes completely initialized. 

SYNTAX 

VOID wpObjectReady (ULONG ulCode, WPObject * refObject) 
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PARAMETERS 

ulCode - input 

The following flags are ORed together to provide information about 
how the object was instantiated: 

Constant _ Description _ 


OR_NEW 

0x01 

This is a new object that has 
been created. 

OR_AWAKE 

0x02 

This object already existed and 
has just been awakened. 

OR_REFERENCE 

0x10000000 

The refObject parameter has 
been set. 

OR_FROMTEMPLATE 

0x10000004 

This object was created from 
the template refObject. 

OR_FROMCOPY 

0x10000008 

This object was copied from 
the object refObject. 

OR_SHADOW 

0x10000010 

This object was just created as 
a shadow of refObject. 


refObject - input 

The pointer to the reference object this object was created from if 
ulCode contains OR_REFERENCE. Otherwise it is set to NULL. 

RETURNS 

none 

HOWTO CALL 

This method is generally called only by the system. 

HOWTO OVERRIDE 

Override this method for notification when an object has become fully 
initialized after its instantiation. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpIsObjectlnitialized -56, wpSetup -63, wpSetupOnce -64 
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• wpQueryHandle WPObJect instance method 


Returns the handle of an object. 

SYNTAX 

HOBJECT wpQueryHandle ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—The persistent handle of the object. 
NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method on any object to retrieve its persistent handle. This 
handle can be used at any time to get the object pointer using 
wpclsQueryObject or wpclsObjectFromHandle (Warp). 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinQueryObject-17, wpclsObjectFromHandle -72, 
wpclsQueryObject -75, WinCreateObject -9, WinDestroyObject -13, 
WinSetObjectData -22 

NOTES 

Workplace objects, other than transients, are not always loaded in mem¬ 
ory. If an object must be accessed but it might not be awake and in 
memory, the persistent object handle can be used with the wpclsQuery¬ 
Object method to wake up the object. wpclsQueryObject can also be 
used if the object is already awake but the SOM pointer is not known. 
Object handles are also useful for non-SOM applications on a separate 
process that manipulate Workplace Shell objects. A Workplace object 
can query its handle with wpQueryHandle and then pass it to another 
process. The other process could then call WinSetObjectData or 
WinDestroyObject with this handle. 



Object Manipulation 


61 


RESTRICTIONS/WARNINGS 

<®> File system objects are not assigned handles until wpQueryHandle is 
called. The handles for these objects are stored in a table in the 
os2sys.ini file that is also kept in memory. wpQueryHandle should 
be used sparingly on file system objects because if it were called on 
all files on the system, the large size of the table would greatly affect 
system performance. 


• wpScanSetypStriog WPObject instance method 


Parses a setup string. 

SYNTAX 

BOOL wpScanSetupString (PSZ pszSetupStrinz PSZ pszKey, PSZ pszValue, 

PULONG pcbValue) 


PARAMETERS 

pszSetupString - input 

List of keyname value pairs separated by semicolons. Setup strings are 
passed to objects via the wpSetup method. 
pszKey - input 

The keyname that represents the data that is to be extracted from the 
setup string. See Appendix A for the list of possible keyname value 
pairs for the predefined Workplace Shell classes. 
pszValue - input/output 

The buffer to place the data extracted from the setup string. If NULL 
is specified, the required size for the buffer is returned in pcbValue. 
pcbValue - input/output 

If pszValue is nonzero, set pcbValue to point to the size of pszValue. If 
pszValue is NULL, the required size for the buffer is returned in this 
parameter. 

RETURNS 

TRUE—The specified keyname was found and if pszValue was non-null, 
the data was copied to the buffer. 

FALSE—An error occurred or the keyname was not found. 
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HOWTO CALL 

Call this method on any object to parse a setup string. This method is 
usually called from an override of the wpSetup method to extract 
setup data. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinSetObjectData -22, WinCreateObject -9, wpclsNew -71, 
wpSetup -63 

SAMPLE CODE 

A setup string is a list of keyname value pairs separated by semicolons. 
For example, the setup string, << NODELETE=YES;NOMOVE=YES; 
OBJECTID=<MY_OBJECTID>” would be used to set up an object such 
that its object ID is <MY_OBJECTID>, it is not deleteable, and it is not 
moveable. Classes can define their own keyname value pairs to allow 
instance data or other values to be set via wpSetup. The following sam¬ 
ple is an override of the wpSetup method from the source of a class 
called MyClass. 

SOM_Scope BOOL SOMLINK mels_wpSetup(MyClass *somSelf, 

PSZ pszSetupString) 

{ 

ULONG cbValue; 

BOOL bReturn; 

MyClassData *somThis = MyClassGetData(somSelf); 
cbValue = 0; 

/* find the value "NAME" in the setup string and set the instance 
data _pszName on this object 
*/ 

.bReturn = _wpScanSetupString(somSelf, pszSetupString, "NAME", 

NULL, &cbValue); 

if (bReturn && cbValue) 

{ 

_pszName = (PSZ) _wpAllocMem(somSelf, cbValue, NULL); 
if (_pszName) 
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_wpScanSetupString(somSelf, pszSetupString, "NAME", 
_pszName, &cbValue); 

} 

return parent_wpSetup(somSelf, pszSetupString); 


® wpSetup WPObJect instance method 

Sets or changes the settings of an object. 

SYNTAX 

BOOL wpSetup (PSZ pszSetupString ) 

PARAMETERS 

pszSetupString - input 

List of keyname value pairs separated by semicolons. See Appendix A 
for the list of possible keyname value pairs for the predefined 
Workplace Shell classes. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to pass it a setup string to set data. 
wpSetup does not need to be called just after creating an object; 
wpclsNew and WinCreateObject both have setup string parameters 
that will be passed to the object when the system calls wpSetup. 

HOWTO OVERRIDE 

Override this method to extract the class-defined data from the setup 
string, using wpScanSetupString to parse the string. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinSetObjectData -22, WinCreateObject -9, wpclsNew -71, 
wpRestoreState -89, wpSaveState -97, wpScanSetupString -61, 
wpSetupOnce -64 
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NOTES 

A setup string is a list of keyname value pairs separated by semicolons. 
For example, the setup string “NODELETE=YES;NOMOVE=YES; 
OBJECTID=<MY_OBJECTID>” would be used to set up an object such 
that its object ID is <MY_OBJECTID>, it is not deleteable, and it is not 
moveable. Classes can define their own keyname value pairs to allow 
instance data or other values to be set via wpSetup. If it is necessary to 
have a literal semicolon as part of the data, put a carat ( A ) before the 
semicolon; otherwise it will be treated as a separator between keyname 
value pairs. Whenever possible, use commas to separate multiple val¬ 
ues for one keyname. 

RESTRICTIONS/WARNINGS 

• wpSetup is called when the object is first created and could be called 
again by any application or as a result of any application calling 
WinSetObjectData or SysSetObjectData. If a setup keyname must be 
processed only once (when the object has just been created), 
wpSetupOnce (Warp) should be overridden to handle this. 

• The system will always call wpSaveDeferred on an object immedi¬ 
ately after it calls wpSetup. Therefore, it is not necessary to make the 
call to wpSaveDeferred from within a wpSetup override . However, 
wpSaveDeferred should be called by any application after calling 
wpSetup. 


• wpSetupOnce WPObJeet instance method (Warp only) 


Sets or changes the settings of an object when it is first created. 

SYNTAX 

BOOL wpSetupOnce (PSZ pszSetupString) 

PARAMETERS 

pszSetupString - input 

List of keyname value pairs separated by semicolons. See Appendix A 
for the list of possible keyname value pairs for the predefined 
Workplace Shell classes. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method is called exactly once by the system for each object, 
namely when the object is created. Do not call this method directly. 

HOWTO OVERRIDE 

Override this method to extract the class-defined data from the setup 
string, using wpScanSetupString to parse the string. The parent 
method must be called, which will invoke the wpSetup method with the 
same setup string. Therefore, do not process any setup keynames that 
are already processed in the wpSetup override. Any other one-time 
setup for an object should be done from within this override as well. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinSetObjectData -22, WinCreateObject -9, wpclsNew -71, 
wpRestoreState -89, wpSaveState -97, wpScanSetupString -61, 
wpSetup -63 

NOTES 

A setup string is a list of keyname value pairs separated by semicolons. 
For example, the setup string “NODELETE=YES;NOMOVE=YES; 
OBJECTID=<MY_C)BJECTI1)>” would be used to set up an object such 
that its object ID is <MY_OBJECTID>, it is not deleteable, and it is not 
moveable. Classes can define their own keyname value pairs to allow 
instance data or other values to be set via wpSetup. If it is necessary to 
have a literal semicolon as part of the data, put a carat ( A ) before the 
semicolon; otherwise it will be treated as a separator between keyname 
value pairs. Whenever possible, use commas to separate multiple val¬ 
ues for one keyname. 

RESTRICTIONS/WARNINGS 

<® It is not necessary to call wpSaveDeferred from within the wpSetup- 
Once method. The system will call wpSaveDeferred on the object 
after wpSetupOnce has been invoked. 


• wpUnlockObJect WPObJeet instance method 


Reduces an object’s lock count by one. 
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SYNTAX 

BOOL wpUnlockObject ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to decrement its lock count by one. 
When the lock count reaches zero, the object will go dormant. This 
method has no effect on WPTransient descendants. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAddToObjUseList -145, wpclsNew -71, wpclsQueryObject -75, 
wpCopyObject -44, wpCreateAnother -47, wpCreateFromTemplate -48, 
wpCreateShadowObject -50, wpIsLocked -55, wpLockObject -56, 
wpPopulate -242, wpQueryContent -243, wpQueryHandle -60 

NOTES 

The lock count is an internal counter the WPObject class defines to 
keep track of whether an object is needed in memory. The system, will 
increment the lock count of an object once for every open view in the 
in-use list, once for every open folder view the object is contained in, 
once for every shadow of the object, once for every contained object if 
the object is a folder, and once every time a method is called with the 
fl^ock parameter set to TRET. It is the application’s responsibility to 
call wpUnlockObject after locking an object. 

RESTRICTIONS/WARNINGS 

m If you call the wpPopulate method on a folder, the system will lock 
all the folder’s contents once. You must call wpUnlockObject on 
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each object contained in the folder when they are no longer needed 
(use wpQueryContent to enumerate the contents of the folder). 

<1 wpLockObject was not externalized before Warp. A workaround for 
locking an object would be to call wpQueryHandle to get the ob¬ 
ject’s handle and then wpclsQueryObject on the returned handle. 
Since the object is already awake, the only effect wpclsQueryObject 
will have is to lock the object. Be aware that wpQueryHandle use on 
file system objects should be done in moderation. 


Class Methods 


wpclsCreateDefaultTemplates creates class templates in the templates 
folder (pg. 67). 

wpclsDecUsage (Warp) decrements the usage count of a class by one 
(pg. 69). 

wpclsIncUsage (Warp) increments the usage count of a class by one 
(pg. 70). 

wpclsNew creates a new instance of a class (pg. 71). 
wpclsObjectFromHandle (Warp) returns the SOM pointer for an ob¬ 
ject, given its handle (pg. 72). 

wpclsQueryAwakeObject (Warp) tests if a file system object is awake 
(pg.73). 

wpclsQueryFolder returns the SOM pointer for a folder, given its loca¬ 
tion (pg. 74). 

wpclsQueryObject returns the SOM pointer for an object, given its 
handle (pg. 75). 

wpclsQueryObjectFromPath returns the SOM pointer for a file system 
object, given its location (pg. 76). 


® wpelsCreateDefauStTempfates WPQbject class method 


Creates class templates in the templates folder. 

SYNTAX 

BOOL wpclsCreateDefaultTemplates (WPFolder * Folder) 
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PARAMETERS 

Folder - input 

The object pointer for the folder in which to place the templates. 

RETURNS 

TRUE—Templates have been created. 

FALSE—No templates have been created. 

HOWTO CALL 

This method is generally called only by the Templates folder, when it is 
populated, on any class that does not have the CLSSTYLE_NEV- 
ERTEMPLATE style. If the method returns TRUE, the Templates 
folder takes no action. If it returns FALSE, the Templates folder will 
create one nondeleteable template for the class. 

HOWTO OVERRIDE 

Override this method to create one or more templates in the 
Templates folder and return TRUE if successful. Do not call the parent 
method or the parent classes might create duplicate templates. 
WPObject takes no action for this method and only returns FALSE. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsNew -71, wpclsQueryStyle -127 

RESTRICTIONS/WARNINGS 

• If your subclass should never have template instances, override 
wpclsQueryStyle and OR the CLSSTYLEJNEVERTEMPLATE style 
with the return code from the parent method, 
e To prevent the Templates folder from creating templates of your 
class, override wpclsCreateDefaultTemplates and return TRUE. 

SAMPLE CODE 

The following sample is an override of the wpclsCreateDefault¬ 
Templates method by the class called MyClass. 

SOM_Scope BOOL SOMLINK mclsM_wpclsCreateDefaultTemplates 

(M_MyClass *somSelf / 
WPFolder *Folder) 
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{ 

MyClass *NewTemplate; 

/* note somSelf is a class pointer in this override so it can be 
passed to wpclsNew. 

*/ 

NewTemplate = _wpclsNew(somSelf,_wpclsQueryTitle(somSelf), 

"TEMPLATE^YES", 

Folder, 

FALSE); 

if (NewTemplate) 
return TRUE; 
else 

return FALSE; 


} 


® wpcIsDecUsage WPObject class method (Warp only) 


Decrements the usage count of a class by one. 

SYNTAX 

VOID wpcIsDecUsage ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

Call this method on a class object pointer to decrement its usage count 
once. Only call this method if wpclsIncUsage was previously called. 

HOWTO OVERRIDE 

This method is generally not overridden. 


OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpclsIncUsage -70 

NOTES 

The system uses the class usage count to determine whether the class 
should be unloaded. The usage count is automatically incremented by 
the system when an instance is created and decremented when an in¬ 
stance goes dormant. Once the count goes back to zero, the class DLL 
is unloaded. 


# wpclsIncUsage WPObJect class method (Warp only) 

Increments the usage count of a class by one. 

SYNTAX 

VOID wpclsIncUsage ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

Call this method on a class object pointer to increment its usage count, 
thus preventing the system from unloading the class. 

HOWTO OVERRIDE 

This method is generally not overridden. 


OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpclsDecUsage -69 

MOTES 

The system uses the class usage count to determine whether the class 
should be unloaded. The usage count is automatically incremented by 
the system when an instance is created and decremented when an in¬ 
stance goes dormant. Once the count goes back to zero, the class DLL 
is unloaded. 


# wpcIsNew WPObject class method 


Creates a new instance of a class. 

SYNTAX 

WPObject * wpclsNew (PSZ pszTitle, PSZ pszSetupEnv, WPFolder * Folder, 
BOOL fLock) 


PARAMETERS 

pszTitle - input 

The title of the new object. 

pszSetupEnv - input 

The initial settings for the new object in the form of a setup string. A 
setup string is a list of keyname value pairs separated by semicolons 
which is parsed by the object for initialization. Specify NULL to use the 
object’s defaults. See Appendix A for the list of available keyname 
value pairs for the predefined Workplace Shell classes. For more infor¬ 
mation on setup strings, see wpSetup (pg. 63). 

Folder - input 

The object pointer of the folder in which to place the new object. Some 
methods for obtaining Folder object pointers are wpclsQueryFolder, 
wpclsQueryObject, and wpclsQueryObjectFromPath. 
fLock - input 

TRUE—Increment the lock count on the new object returned. 

FALSE—Do not increment the lock count on the new object. 

RETURNS 

(nonzero value)—The object pointer for the new object. 

NULL—An error occurred. 
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HOWTO CALL 

Call this method on any class that supports creating instances. 
(WPObject and the base classes cannot have instances) This method 
must be used instead of somNew because Workplace objects require 
special processing when they are created. 

HOWTO OVERRIDE 

This method can be overridden for notification when new objects are 
created, but its functionality cannot be completely replaced so be sure 
to first call the parent method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinCreateObject -9, wpclsQueryFolder -74, wpclsQueryObject -75, 
wpclsQueryObjectFromPath -76, wpCreateFromTemplate -48, 
wpDelete -51, wpFree -53, wpSetup -63, wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

9 Pass TRUE for the /Lock parameter if you are going to access the ob¬ 
ject pointer after calling wpclsNew. When the pointer is no longer 
needed, call wpUnlockObject. 

• wpclsNew is called by the system whenever a new object is created by 
any method except wpCreateFromTemplate. 


@ wpdsObjectFromHandle WPObject class 

method (Warp only) 

Returns the SOM pointer for an object, given its handle. 

SYNTAX 

WPObject * wpdsObjectFromHandle (HOBJECT hObject ) 

PARAMETERS 

hObject - input 

The object handle of any Workplace Shell object. 
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RETURNS 

(nonzero value)—The SOM object pointer. 

NULL—An error occurred or the object cannot be found. 

HOWTO CALL 

Call this method on the WPObject class object (_WPObject) to get the 
object pointer for any object. If the object is not awake, Workplace will 
awaken it and then return the pointer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinQueryObject -17, wpclsQueryFolder -74, wpclsQueryObject -75, 
wpclsQueryObjectFromPath -76, wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

® wpclsObjectFromHandle will increment the lock count for the re¬ 
turned object pointer. When the pointer is no longer needed, call 
wpUnlockObject. 

® If the handle of the object is not known but the object ID is, call 
WinQueryObject on the object ID to obtain the object handle. 


# wpcIsQueryAwakeObject WPFileSystem 

class method (Warp only) 


Tests if a file system object is awake. 

SYNTAX 

WPObject * wpcIsQueryAwakeObject (PSZ pszInputPath) 

PARAMETERS 

pszInputPath - input 

The fully qualified path of a file system object. 
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RETURNS 

(nonzero value)—The pointer to the specified object. 

NULL—The object is not awake or was not found. 

HOWTO CALL 

Call this method on the WPFileSystem class object (_WPFileSystem) to 
determine if a file system object is awake. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpfsys.h 

SEE ALSO 

wpclsQueryFolder -74, wpclsQueryObject -75, 
wpclsQueryObjectFromPath -76 

RESTRICTIONS/WARNINGS 

• Although the pointer returned from this method is of the type 
WPObject, this method only returns WPFileSystem objects. 


# wpclsQue ryFolder WPObject class method 

Returns the SOM object pointer for a folder, given its location. 

SYNTAX 

WPFolder * wpclsQueryFolder (PSZ pszLocation, BOOL f.Lock) 

PARAMETERS 

pszLocation - input 

This can be either the object ID of the folder (if it exists and is known) 
or the fully qualified path of the directory represented by the folder. 
Refer to Appendix D for a list of default Workplace folder object IDs. 
fLock - input 

TRUE—Increment the lock count on the object returned. 

FALSE—Do not increment the lock count on the object. 
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RETURNS 

(nonzero value)—The object pointer for the folder. 

NULL—An error occurred or the object is not a folder. 

HOWTO CALL 

Call this method on the WPObject class object (_WPObject) to get the 
object pointer for a folder. If the folder is not awake, Workplace will 
awaken it and then return the pointer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryObject -75, wpclsQueryObjectFromPath -76, 
wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

® Pass TRUE for the fLock parameter if you are going to access the ob¬ 
ject pointer after calling wpclsQueryFolder. When the pointer is no 
longer needed, call wpUnlockObject. 


© wpclsQueryObject WPObject class method 

Returns the SOM pointer for an object, given its handle. 

SYNTAX 

WPObject * wpclsQueryObject (HOBJECT hObject) 

PARAMETERS 

hObject - input 

The object handle of any Workplace Shell object. 

RETURNS 

(nonzero value)—The SOM object pointer. 

NULL—An error occurred or the object cannot be found. 
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HOWTO CALL 

Call this method on the WPObject class object (_WPObject) to get the 
object pointer for any object. If the object is not awake, Workplace will 
awaken it and then return the pointer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinQueryObject -17, wpclsObjectFromHandle -72, 
wpclsQueryFolder -74, wpclsQueryObjectFromPath -76, 
wpUnlockObject -65 

RESTRICTIONS,WARNINGS 

® wpclsQueryObject will increment the lock count for the returned ob¬ 
ject pointer. When the pointer is no longer needed, call wpUnlock¬ 
Object. 

• If the handle of the object is not known but the object ID is, call 
WinQueryObject on the object ID to obtain the object handle. 


@ wpclsQueryObjectFromPath WPFiSeSystem 

_ class method __ 

Returns the SOM object pointer for a file system object, given its lo¬ 
cation. 

SYNTAX 

WPFileSystem * wpclsQueryObjectFromPath (PSZ pszFQPath) 

PARAMETERS 

pszFQPath - input 

This can be either the object ID of the file system object (if it exists and 
is known) or the fully qualified path of the file or directory rep¬ 
resented by the object. See Appendix D for a list of predefined 
Workplace object IDs. 
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RETURNS 

(nonzero value)—The requested object pointer. 

NULL—-An error occurred. 

HOWTO CALL 

Call this method on the WPFileSystem class object (_WPFileSystem) to 
get the object pointer for a file or folder. If the object is not awake, 
Workplace will awaken it and then return the pointer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpfsys.h 

SEE ALSO 

WinQueryObject -17, wpclsObjectFromHandle -72, 
wpclsOueryAwakeObject -73, wpclsQueryFolder -74, 
wpclsQueryObject -75, wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

® This method will increment the lock count of the returned object 
pointer. When the pointer is no longer needed, call wpUnlockObject. 
# There is no equivalent method for abstract objects. To get the object 
pointer of an abstract given an object ID, call WinQueryObject to 
get the HOBJECT and pass that to wpclsQueryObject or wpcls¬ 
ObjectFromHandle (Warp). 
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Instance and 
Class Data 


O bject class definitions can specify both instance and class data. 

The instance data is allocated for each object to allow them to 
separately maintain individual information. Only one class object 
exists for each loaded class; therefore, only one copy of class data re¬ 
sides in memory. Class data and instance data can be obtained by call¬ 
ing the M_<classname>GetData macro on the class object or the 
<classname>GetBata macro on an object, respectively. 
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initializing and Uninitializing Data 

When a class is loaded, the system calls wpclsInitData to allow the class 
to allocate and initialize any required resources for its data (such as 
memory or module handles). As each instance is awakened, 
wpInitData is called to allow the object to allocate and initialize its in¬ 
stance data. wpclsInitData and wpInitData should be overridden by the 
subclass to allocate and initialize class and instance data defined by the 
subclass. 

When a class is unloaded, the system calls wpclsUnlnitData to al¬ 
low the class to deallocate its resources. wpUnlnitData is called on 
each instance as it is made dormant to allow the object to deallocate its 
instance data. If resources are allocated in a wpclsInitData override, 
wpclsUnlnitData must also be overridden to free them. Furthermore, 
any resources allocated in a wpInitData override must be freed from 
within wpUnlnitData. 

Saving Data 

When the instance data of an object has changed and must be saved, 
call the wpSaveDeferred method to mark the object as “dirty.” The 
Workplace Shell has a separate thread for saving dirty objects which, af¬ 
ter approximately five seconds, will call wpSavelmmediate on each 
one. wpSavelmmediate can also be called directly on an object to cause 
it to save its state immediately instead of asynchronously, but this can 
affect the performance of the system. The base classes WPFileSystem 
and WPAbstract provide persistent storage for instance data and 
process wpSavelmmediate by calling wpSaveState and wpRestoreState 
on the dirty object. These methods should be overridden to save and 
restore instance data, respectively. 

Workplace does not provide methods for saving class data. Classes 
must provide their own storage mechanisms for saving and restoring 
this data. Class data should be restored in the override of wpclsInitData 
and should be saved whenever the data is changed. 

Restrictions and Warnings 

• Class data should not be saved in the wpclsUnlnitData method over¬ 
ride because this method is not called when the user shuts down the 
system. 
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Instance Methods 


wpAUocMem allocates a block of memory of a specified size (pg. 80). 
wpFreeMem frees memory allocated with wpAllocMem (pg. 82). 
wpInitBata initializes an object’s data when created (pg. 83). 
wpRestoreBata restores instance data stored as a block of binary data 
(pg. 84). 

wpRestoreLong restores instance data stored as a long (pg. 87). 
wpRestoreState notifies the object to restore its instance data 
(pg. 89). 

wpRestoreString restores instance data stored as a string (pg. 90). 
wpSaveBata saves instance data as a block of binary data (pg. 92). 
wpSaveBeferred marks an object to save its state asynchronously 
(pg. 94). 

wpSavelmmediate causes an object to save its state synchronously 
(pg. 95). 

wpSaveJLong saves instance data as a long (pg. 96). 
wpSaveState notifies an object to save its instance data (pg. 97). 
wpSaveString saves instance data as a string (pg. 98). 
wpUnlnitBata uninitializes an object’s data (pg. 100). 


@ wpAISocHem WPObject instance method 


Allocates a block of memory of a specified size. 

SYNTAX 

PBYTE wpAllocMem (ULONG cbBytes, PULONG prc) 

PARAMETERS 

cbBytes - input 

The size, in bytes, of the requested block of memory. 
prc - output 

A pointer to the error returned from BosAllocMem. Specify NULL 
and Workplace will display the error to the user instead. 

RETURNS 

(nonzero value)—The requested block of memory. 

NULL—An error occurred. 
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HOWTO CALL 

Call this method on any object to allocate memory. When the memory 
is no longer needed, call wpFreeMem. The system will call this method 
to allocate memory for objects. 

HOWTO OVERRIDE 

Override this method to replace the memory allocation scheme for 
your objects. Do not call the parent method. If this method is overrid¬ 
den, wpFreeMem must also be overridden so the memory will be prop¬ 
erly freed. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAddToObjUseList -145, wpFreeMem -82, wpUnlnitData -100 

NOTES 

When this method is called, the system puts a USAGEJVIEMORY item 
in the in-use list for the object. See Chapter 6 for more information 
about in-use lists. If the object is deleted or goes dormant, 
wpUnlnitData is called and the WPObject implementation for 
wpUnlnitData will look through the in-use list for USAGEJMEMORY 
items and call wpFreeMem on each one that is found. 

If this method is overridden, the replacing implementation 
should also put a USAGE_MEMORY item in the in-use list so that the 
system can detect memory that has not been freed when 
wpUnlnitData is called. 

RESTRICTIONS/WARNINGS 

® Since WPObject frees any memory allocated with wpAllocMem in 
wpUnlnitData, a class that overrides wpUnlnitData should either 
not free any of this memory still allocated, or free it with 
wpFreeMem before calling the parent method. Otherwise, the mem¬ 
ory will be freed twice. 

SAMPLE CODE 

The following sample is a method called SetComment defined by the 
class MyClass. The purpose of this method is to set an instance variable 
called pszComment using wpAllocMem to allocate the memory. 
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SOM_Scope BOOL SOMLINK mels_SetComment(MyClass *somSelf, 

PSZ pszNewString) 

{ 

BOOL bReturn = TRUE; 

MyClassData *somThis = MyClassGetData(somSelf); 

/* if _pszComment is already set to something, free it */ 
if (_pszComment) 

_wpFreeMem(somSelf, (PBYTE) _pszComment); 

/* if pszNewString is not NULL, allocate memory for the string and 
copy the new string. Otherwise just set pszComment to NULL. 
_pszComment should be freed in the wpUnlnitData override if it is 
non-NULL. 

*/ 

if (pszNewString) 

{ 

_pszComment 4 _wpAllocMem(somSelf, strlen(pszNewString) + 1, 

NULL); 


if (_pszComment) 

strepy(_pszComment, pszNewString); 
else 

/* error allocating memory */ 
bReturn = FALSE; 

} 

else 

_pszComment = NULL; 
return(bReturn); 


$> wpFreeMem WPObJect instance method 

Frees memory allocated with wpAllocMem. 

SYNTAX 

BOOL wpFreeMem (PBYTE pByte) 

PARAMETERS 

pByte - input 
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A pointer to the block of memory to be freed. It must have been allo¬ 
cated using wpAllocMem. 

RETURNS 

TRUE—The memory was freed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on an object to free memory that was allocated with 
wpAllocMem. The system also calls this method to free an object’s 
memory. 

HOWTO OVERRIDE 

Override this method to replace the memory allocation scheme for 
your objects if the wpAllocMem method was also overridden. Do not 
call the parent method. The wpAllocMem override should have added 
USAGE_MEMORY items to the in-use list. Remove the USAGE_MEM- 
ORY item that corresponds to the memory block that is freed. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAllocMem -80, wpDeleteFromObjUseList -148, wpUnlnitData -100 

RESTRICTIONS/WARNINGS 

© Since WPObject frees any memory allocated with wpAllocMem in 
wpUnlnitData, a class that overrides wpUnlnitData should either 
not free any of this memory still allocated, or free it with 
wpFreeMem before calling the parent method. Otherwise, the mem¬ 
ory will be freed twice. 


• wplnitOata WPObject instance method 

Initializes an object’s data when created. 

SYNTAX 

VOID wplnitOata ( ) 
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PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method is called only by the system. 

HOWTO OVERRIDE 

Override this method to initialize an object to a known state. The par¬ 
ent method should be called first, which will initialize all of the in¬ 
stance data to zero. wpUnlnitData should be overridden to free any 
memory that was allocated in this override. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAllocMem -80, wpFreeMem -82, wpSetup -63, wpSetupOnce -64, 
wpUnlnitData -100 

NOTES 

The system calls this method each time an object is created or awak¬ 
ened. If there is setup processing for an object that needs to be done 
only once, use the wpSetupOnce (Warp) method. 

RESTRICTIONS/WARNINGS 

• wpInitData is called before an object is initialized. Since many 
Workplace methods do not work properly unless an object is initial¬ 
ized, calling predefined Workplace methods from this override is 
not advised. 


• wpRestoreData WPObJect Instance method 


Restores instance data stored as a block of binary data. 

SYNTAX 

BOOL wpRestoreData (PSZ pszClass , ULONG ulKey, PBYTE pValue, 

PULONG pcbValue) 
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PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to restore. 
pValue - input/output 

The buffer to hold the requested data. If NULL is specified, the re¬ 
quired size will be returned in pcbValue . 
pcbValue - input/output 

The address of the size of the pValue buffer. If NULL is specified for 
pValue, the required size is returned in this parameter. 

RETURNS 

TRUE—The data for the specified ulKey was found and the call was 
successful. 

FALSE—An error occurred or the specified ulKey was not found. 

HOWTO CALL 

This method can only be called from an override of wpRestoreState to 
restore data that was saved with wp Save Data. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreLong -87, wpRestoreState -89, wpRestoreString -90, 
wpSaveData -92, wpSaveDeferred -94, wpSavelmmediate -95, 
wpSaveLong -96, wpSaveState -97, wpSaveString -98 

NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
class. If an instance variable is saved using a specific key, that variable 
must be restored with the same value. 
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RESTRICTIONS/WARNINGS 

# If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 

SAMPLE CODE 

This sample is an override of the wpRestoreState method to demon¬ 
strate restoring instance data using wpRestoreData for a class called 
MyClass. 

#define IDKEY_DATA 1 // the next keys would be 2,3,4 and so on 
CHAR szClassName[] = "MyClass"; 


SOM_Scope BOOL SOMLINK mcls_wpRestoreState(MyClass *somSelf, 

ULONG ulReserved) 

{ 

ULONG ulSize; 

MyClassData *somThis = MyClassGetData(somSelf); 

/* restore the PVOID instance data called pData */ 
if ( _wpRestoreData(somSelf, szClassName, IDKEY_DATA, NULL, 
&ulSize)) 

{ 

_pData = _wpAllocMem(somSelf, ulSize, NULL); 
if ( _pData) 

{ 

_wpRestoreData(somSelf, szClassName, IDKEY_DATA, _pData, 
&ulSize); 

/* save the size in the ULONG instance data called _ulDataSize 
*/ 

_ulDataSize = ulSize; 

} 

} 

return (parent_wpRestoreState(somSelf,ulReserved)); 
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<§> wp Restore Long WPObJect Instance method 

Restores instance data stored as a long. 

SYNTAX 

BOOL wpRestoreLong (PSZ pszClass , ULONG ulKey , PULONG 

pulValue) 


PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to restore. 
pulValue - output 

The address of the returned long value. 

RETURNS 

TRUE—The value for the specified ulKey was found and the call was 
successful. 

FALSE —An error occurred or the specified ulKey was not found. 

HOWTO CALL 

This method can only be called from an override of wpRestoreState to 
restore data that was saved with wpSaveLong. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreData -84, wpRestoreState -89, wpRestoreString -90, 
wp Save Data -92, wp S ave Deferred -94, wpSavelmmediate -95, 
wpSaveLong -96, wpSaveState -97, wpSaveString -98 
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NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
class. If an instance variable is saved using a specific key, that variable is 
restored with the same value. 

RESTRICTIONS/WARNINGS 

• If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 

SAMPLE CODE 

This sample is an override of the wpRestoreState method to demon¬ 
strate restoring instance data using wpRestoreLong for a class called 
MyClass. 

#define IDKEY_FLAG 2 // the next keys would be 3,4 and so on 
CHAR szClassName[] = "MyClass"; 


SOM_Scope BOOL SOMLINK mcls_wpRestoreState(MyClass *somSelf, 

ULONG ulReserved) 


ULONG ulValue; 

MyClassData *somThis = MyClassGetData(somSelf) ; 

/* restore the ULONG instance data called ulFlag. */ 

if ( _wpRestoreLong(somSelf, szClassName, IDKEY_FLAG, 
&ulValue)) 


/* do not set _ulFlag unless the data was previously saved */ 
_ulFlag = ulValue; 

} 

return (parent_wpRestoreState(somSelf,ulReserved)); 
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© wpRest©reState WPObject instance method 

Notifies an object to restore its instance data. 

SYNTAX 

BOOL wpRestoreState (ULONG ulReserved) 

PARAMETERS 

ulReserved - reserved 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can only be called by the system when an object is awak¬ 
ened. 

HOWTO OVERRIDE 

Override this method to restore data that was saved in wpSaveState. 
Use wpRestoreData, wpRestoreLong, and wpRestoreString. You must 
call the parent method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreString -90, 
wp Save Data -92, wpSaveDeferred -94, wpSavelmmediate -95, 
wpSaveLong -96, wpSaveState -97, wpSaveString -98 

NOTES 

wpRestoreState should only be overridden if the wpSaveState method 
was also overridden to save instance data. 

SAMPLE CODE 

See the samples for wpRestoreData, wpRestoreLong, and wpRestore¬ 
String. 
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• wpRestoreString WPObJect instance method 


Restores instance data stored as a string. 

SYNTAX 

BOOL wpRestoreString (PSZ pszClass, ULONG ulKey, PSZ pszValue, 

PULONG pcbValue) 


PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to restore. 
pszValue - input/output 

The buffer to hold the requested string. If NULL is specified, the re¬ 
quired size will be returned in pcbValue . 
pcbValue - input/output 

The address of the size of the pszValue buffer. If NULL is specified for 
pszValue, the required size is returned in this parameter. 

RETURNS 

TRUE—The value for the specified ulKey was found and the call was 
successful. 

FALSE—An error occurred or the specified ulKey was not found. 

HOWTO CALL 

This method can only be called from an override of wpRestoreState to 
restore data that was saved with wpSaveString. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreState -89, 
wpSaveData -92, wpSaveDeferred -94, wpSavelmmediate -95, 
wpSaveLong -96, wpSaveState -97, wpSaveString -98 

NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
class. If an instance variable is saved using a specific key, that variable 
must be restored with the same value. 

RESTRICTIONS/WARNINGS 

• If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 

SAMPLE CODE 

This sample is an override of the wpRestoreState method to demon¬ 
strate restoring instance data using wpRestoreString for a class called 
MyClass. 

#define IDKEY_COMMENT 3 // the next keys would be 4,5,6 and so on 
CHAR szClassName[] = "MyClass"; 


SOM_Scope BOOL SOMLINK mcls_wpRestoreState(MyClass *somSelf, 

ULONG ulReserved) 

{ 

ULONG ulSize; 

MyClassData *somThis = MyClassGetData(somSelf); 

/* restore the PSZ instance data called pszComment */ 

if ( _wpRestoreString(somSelf, szClassName, IDKEY_COMMENT, NULL, 
&ulSize)) 

{ 

_pszComment = (PVOID) _wpAllocMem(somSelf, ulSize, NULL); 


if ( _pszComment) 
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_wpRestoreString(somSelf, szClassName, IDKEY_COMMENT, 
_pszComment, &ulSize); 

} 

return (parent_wpRestoreState(somSelf,ulReserved)); 


© wpSaveData WPObject instance method 

Saves instance data as a block of binary data. 

SYNTAX 

BOOL wpSaveData (PSZ pszClass, ULONG ulKey, PBYTE pValue , 
ULONG cbValue,) 


PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to save. 
pValue - input 

The buffer that holds the data to save. 
cbValue - input 

The size of the pValue buffer. 

RETURNS 

TRUE—The data was saved successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can only be called from an override of wpSaveState. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreState -89, 
wpRestoreString -90, wpSaveDeferred -94, wpSavelmmediate -95, 
wpSaveLong -96, wpSaveState -97, wpSaveString -98 

NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
class. If an instance variable is saved using a specific key, that variable 
must be restored with the same value. 

RESTRICTIONS/WARNINGS 

<n When instance data is saved from the wpSaveState method, the en¬ 
tire block of data is re-created and overwrites the old one. 
Therefore, if some data was saved on a previous call to wpSaveState 
but should be removed because it is zero or no longer valid, simply 
refrain from saving the data in the wpSaveState override (see sample 
below). 

®> If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 

SAMPLE CODE 

This sample is an override of the wpSaveState method to demon¬ 
strate saving instance data using wpSaveData for a class called 
MyClass. The data being saved is called pData, and the instance data 
ulDataSize is used to keep track of the size of pBata. (See the 
wpRestoreData sample.) 

#define IDKEY_DATA 1 // the next keys would be 2,3,4 and so on 
CHAR szClassName<[>] = "MyClass"; 

SOM_Scope BOOL SOMLINK mcls_wpSaveState(MyClass *somSelf) 

{ 

MyClassData *somThis = MyClassGetData(somSelf); 

/* save the data only if it is non zero. If the data has been 
saved at some point but is now zero, just avoiding calling 
wpSaveData this time will erase the old data. 

*/ 
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if (_pData && _ulDataSize) 

{ 

_wpSaveData(somSelf, szClassName, IDKEY_DATA / _pData, 
_ulDataSize); 

} 

return (parent_wpSaveState(somSelf)); 


# wpSaveDeferred WPObject instance method 

Marks an object to save its state asynchronously. 

SYNTAX 

BOOL wpSaveDeferred ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to notify Workplace to save the object 
asynchronously. After approximately five seconds, a separate thread 
will call wpSavelmmediate on the object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreState -89, wpSavelmmediate -95, wpSaveState -97 

NOTES 

Any time persistent data of an object has been changed, the 
wpSaveDeferred method must be called or the data may not be saved 
if the object goes dormant or the machine is rebooted. If the object 
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must be saved immediately, the wpSavelmmediate method can be 
called directly but could affect system performance. 

The system will call the wpSavelmmediate method if the object is 
still waiting to be saved and it goes dormant or the system is shut down. 


© wpSavelmmediate WPObJect Instance method 

Marks an object to save its state synchronously. 

SYNTAX 

BOOL wpSavelmmediate ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to notify Workplace to save the object 
immediately. This method should only be called directly if very critical 
data has been altered that must be saved right away. Otherwise, use 
wpSaveDeferred. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreState -89, wpSaveDeferred -94, wpSaveState -97 

NOTES 

Any time persistent data of an object has been changed, the 
wpSaveDeferred method must be called or the data will not be saved if 
the object goes dormant or the machine is rebooted. If the object must 
be saved immediately, the wpSavelmmediate method can be called di¬ 
rectly but could affect system performance. 
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• wpSaveLong WPObJeet instance method 


Saves instance data stored as a long. 

SYNTAX 

BOOL wpSaveLong (PSZ pszClass, ULONG ulKey, ULONG ulValue) 

PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to save. 
ulValue - output 
The value to save. 

RETURNS 

TRUE—The data was saved successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can only be called from an override of wpSaveState. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreState -89, 
wpRestoreString -90, wpSaveData -92, wpSaveDeferred -94, 
wpSavelmmediate -95, wpSaveState -97, wpSaveString -98 

NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
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class. If an instance variable is saved using a specific key, that variable is 

restored with the same value. 

RESTRICTIONS/WARNINGS 

m If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 

SAMPLE CODE 

This sample is an override of the wpSaveState method to demonstrate 

saving instance data using wpSaveLong for a class called MyClass. 

#define IDKEY_FLAG 2 // the next keys would be 3,4 and so on 

CHAR szClassName<[>] = "MyClass"; 

SOM_Scope BOOL SOMLINK mcls_wpSaveState(MyClass *somSelf) 

{ 

MyClassData *somThis = MyClassGetData(somSelf); 

_wpSaveLong(somSelf, szClassName, IDKEY_FLAG, _ulFlag); 
return (parent_wpSaveState(somSelf)); 

} 


• wpSaveState WPObject instance method 

Notifies an object to save its instance data. 

SYNTAX 

BOOL wpSaveState ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method can only be called by the system when an object’s state is 
being saved. 

HOWTO OVERRIDE 

Override this method to save instance data of the object by calling 
wpSaveData, wpSaveLong, and wpSaveString. You must call the parent 
method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreState -89, 
wpRestoreString -90, wpSaveData -92, wpSaveDeferred -94, 
wpSavelmmediate -95, wpSaveLong -96, wpSaveString -98 

NOTES 

wpRestoreState should be overridden to restore any data saved from 
the wpSaveState override. 

SAMPLE CODE 

See the samples for wpSaveData, wpSaveLong, and wpSaveString. 


• wpSaveString WPObjeet instance method 


Saves instance data as a string. 

SYNTAX 

BOOL wpSaveString (PSZ pszClass , ULONG ulKey , PSZ pszValue ) 

PARAMETERS 

pszClass - input 

The unique string that represents this class. It is recommended that 
the class name be used because it will be unique in the system. All calls 
to save and restore methods from within a class implementation must 
use the same pszClass value. This parameter is case-sensitive. 
ulKey - input 

The application-defined number that represents the desired instance 
data to save. 
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pszValue - input 

A pointer to the string to save. This pointer cannot be NULL. 

RETURNS 

TRUE—The string was saved successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can only be called from an override of wpSaveState. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpRestoreData -84, wpRestoreLong -87, wpRestoreState -89, 
wpRestoreString -90, wpSaveData -92, wpSaveDeferred -94, 
wpSavelmmediate -95, wpSaveLong -96, wpSaveState -97 

NOTES 

The values used for ulKey are defined by the class and must remain 
consistent. Each key is an index into the data created by the storage 
class. If an instance variable is saved using a specific key, that variable 
must be restored with the same value. 

RESTRICTIONS/WARNINGS 

• When instance data is saved from the wpSaveState method, the en¬ 
tire block of data is re-created and overwrites the old one. 
Therefore, if some data was saved on a previous call to wpSaveState 
but should be removed because it is zero or no longer valid, simply 
refrain from saving the data in the wpSaveState override (see sample 
below). 

® If the format of the data should change or if the instance data is re¬ 
moved from the class definition, the key that was used to represent 
this data cannot be reused because it would break existing instances 
of the class on the user’s machine. Applications that already have 
production versions of classes that customers are using must always 
define new keys that have never been used before. 





100 


Workplace Shell 


SAMPLE CODE 

This sample is an override of the wpSaveState method to demonstrate 
saving instance data using wpSaveString for a class called MyClass. 

ttdefine IDKEY_COMMENT 3 // the next keys would be 4,5,6 and so on 
CHAR szClassName[] = "MyClass"; 


SOM_Scope BOOL SOMLINK mcls_wpSaveState(MyClass *somSelf) 

{ 

MyClassData *somThis = MyClassGetData(somSelf); 

/* only save the data if pszComment is nonzero. */ 
if (_pszComment) 

_wpSaveString(somSelf, szClassName, IDKEY_COMMENT, _pszComment); 
return (parent_wpSaveState(somSelf)); 

} 


# wpUnlnitData WPObject instance method 

Uninitializes an object’s data. 

SYNTAX 

VOID wpUnlnitData ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method is only called by the system. 

HOWTO OVERRIDE 

Override this method to free any memory or other resources allocated 
for an object. Call the parent method last. 


OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpAllocMem -80, wpFreeMem -82, wpInitData -83, wpSetup -63 

NOTES 

The system calls this method each time an object is deleted or made 
dormant. 


Class Methods 


wpclsInitData initializes the class object’s data (pg. 101). 
wpclsUnlnitData uninitializes the class object’s data (pg. 102). 


® wpclsInitData WPObject class method 

Initializes a class object’s data. 

SYNTAX 

VOID wpclsInitData ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method is only called by the system. 

HOWTO OVERRIDE 

Override this method to initialize any class variables or to allocate any 
memory or other resources for the class. Call the parent method first. 
Override wpclsUnlnitData to free these resources. 


OTHER INFO 

Include file: wpobjecth 
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SEE ALSO 

wpclsUnlnitData -102 

NOTES 

A Workplace class is loaded when it is registered or when its first in¬ 
stance is awakened. The system calls this method when the class object 
is created. 

RESTRICTIONS/WARNINGS 

» When this method is invoked, no instances of the class yet exist. 
Therefore, the instance method, wpAllocMem, cannot be used to al¬ 
locate memory from this override. Use DosAllocMem or another 
method of memory allocation. 


# wpcSsUntnitData WPObject class method 

Uninitializes a class object’s data. 

SYNTAX 

VOID wpclsUnlnitData () 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method is only called by the system. 

HOWTO OVERRIDE 

Override this method to free any resources allocated for this class. Call 
the parent method last. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsInitData -102 
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NOTES 

When a class is no longer needed in the system because the last in¬ 
stance has gone dormant, the system calls this method just before the 
class DLL is unloaded. 

RESTRICTIONS/WARNINGS 

© Do not load or link with any DLLs that register an exit list. When 
SOM tries to free the class DLL, it will fail because the Workplace 
process is still active. This will prevent any objects of this class from 
waking up after the class has been unloaded. 




_5 

General Object 
Settings 


S ome instance data can be set for all Workplace Shell objects. 

Examples include the object’s title, icon, details, or style. The 
WPObject class defines these attributes and provides methods for set¬ 
ting and querying the data. Most of these settings have class defaults as 
well as individual instance values. For example, wpclsQueryTitle will 
return the default title for all members of the class but wpQueryTitle 
returns the title of a specific instance. By default, objects will use the 
class defaults. 
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Object Icons 

There are multiple methods for setting and querying the icon that rep¬ 
resents an object, and it is sometimes unclear when to use which meth¬ 
ods. Furthermore, the mechanism for setting default class data differs 
from the mechanism for setting the instance data. 

The class default icon should be specified by overriding 
wpclsQuerylconData and returning the desired icon. wpclsQuerylcon 
is a method that was made public before wpclsQuerylconData was writ¬ 
ten and has now become unnecessary. The icon for an individual ob¬ 
ject can be queried with either wpQuerylcon or wpQuerylconData. 
The icon can be altered by calling wpSetlcon to temporarily change 
the icon for the object or wpSetlconData followed by wpSaveDeferred 
for a persistent change. In Warp, wpclsSetlconData and wpclsSetlcon 
can be used to temporarily change the default icon of a class. 

Device Objects 

The device object classes WPMouse, WPKeyboard, and WPSystem de¬ 
fine setting strings that can be set and queried using wpclsSetSetting 
and wpclsQuerySetting as defined by the WPAbstract class. These 
methods enable applications to modify system default information 
without having to directly access the user ini file. 

Restrictions and Warnings 

® Once a persistent object is created, even if it is only using class de¬ 
fault settings, all data is saved to the object itself. This means that if 
you then change the default settings for your class, it will not neces¬ 
sarily affect instances that have already been created. 


Instance Methods 


wpCnrRefreshDetails (Warp) refreshes the details data of an object 

(pg. 106). 

wpCnrSetEmphasis modifies the container record attributes for an ob¬ 
ject (pg. 107). 

wpModifyStyle changes the style of an object (pg. 108). 
wpQueryConfirmations returns the confirmations set for an object 

(pg. 111). 
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wpQueryCoreRecord (Warp) returns a pointer to the container 
record for an object (pg. 112). 

wpQueryBetailsBata returns the details data of an object (pg. 113). 
wpQuerylcon returns the handle for the icon representing an object 
(pg. 114). 

wpQuerylconData returns the data for the icon representing an object 
(pg. 115). 

wpQueryObjectID (Warp) returns the ID string of an object 
(pg. 117). 

wpQueryStyle returns the style of an object (pg. 118). 
wpQueryTitle returns the title of an object (pg. 118). 
wpSetlcon sets the handle for the icon representing an object 
(pg. 119). 

wpSetlconData sets the data for the icon representing an object 
(pg. 120). 

wpSetStyle sets the style of an object (pg. 121). 
wpSetTitle sets the title of an object (pg. 122). 


# wpCnrRefreshDetails WPObject instance 

method (Warp only) 

Refreshes the details data of an object. 

SYNTAX 

VOID wpCnrRefreshDetails ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

This method should be called when an object’s details data have been 
modified. This will refresh the data displayed in the details view of the 
object’s folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpQueryDetailsData -113 


# wpCnrSetEmphasis WPObject instance method 

Modifies the container record attributes for an object. 

SYNTAX 

BOOL wpCnrSetEmphasis (ULONG ulEmphasisAttr ; BOOL fTurnOn) 

PARAMETERS 

ulEmphasisAttr - input 

The record attribute to modify for this object. Choose one from the 
following list: 


Constant 


Description 

CRA_SELECTED 

0x001 

Record is selected. 

CRA_TARGET 

0x002 

Record has target emphasis. 

CRA_CURSORED 

0x004 

Cursor is on the record. 

CRAJNUSE 

0x008 

Record has in-use emphasis. 

CRAJFILTERED 

0x010 

Record is invisible. 

CRAJDROPONABLE 

0x020 

Record can accept a drop. 

CRA_RECORD READONLY 

0x040 

Record is read-only. 

CRA_EXPANDED 

0x080 

Record is expanded (parent records 
in tree view only). 

CRA_COLLAPSED 

0x100 

Record is collapsed (parent records 
in tree view only). 


fTurnOn - input 

Pass TRUE to set the flags in ulEmphasisAttr and pass FALSE to remove 
them. 
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RETURNS 

TRUE—The record attributes were successfully modified. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to modify the container record 
attributes for an object. These attributes are used for all the views that 
contain this object. The system calls this method to set in-use emphasis 
on objects and to filter objects excluded by the Include page of its 
folder’s settings notebook. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h and pmstddlg.h define: 

IN CL_WINSTD CNR 


• wpModifyStyle WPObJeet instance method 


Changes the style of an object. 

SYNTAX 

BOOL wpModifyStyle (ULONG ulStyleFlags, ULONG ulStyleMask) 

PARAMETERS 

ulStyleFlags - input 

The style flags to be modified for this object. OR together multiple 
style flags to turn on or off more than one flag at once. The following 
is a list of object style flags: 


Constant 

Description 

OBJSTYLE_NOMOVE 

0x02 This object cannot be moved by the 
user. The Move item will not appear 
in the pop-up menu. 

OBJSTYLE_NOLINK 

0x04 A shadow of this object cannot be 
made by the user. The Create 
shadow item will not appear in the 
pop-up menu. 
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OBJSTYLENOCOPY 0x08 

OBJSTYLE_NOT 0x10 

DEFAULTICON 

OBJSTYLE_TEMPLATE 0x20 

OBJSTYLE_NODELETE 0x40 

OBJSTYLE_NOPRINT 0x80 

OBJSTYLE_NODRAG 0x100 

OBJ STYLE_N OTVISIBLE 0x200 


O BJ STYLE_N O SETTIN GS 0x400 

OBJ STYLE_N ORENAME 0x800 

OBJSTYLE_NODROP 0x1000 

OBJSTYLE_NODROPON 0x2000 

OBJSTYLE_CUSTOMICON 0x4000 


This object cannot be copied by the 
user. The Copy item will not appear 
in the pop-up menu. 

The icon for this object should be 
destroyed when the object goes 
dormant. (Use OBJSTYLE_ 
CUSTOMICON in Warp.) 

This object is a template. The 
default drag operation for a 
template object is to create a new 
instance of the same class. 

This object cannot be deleted by the 
user. The Delete item will not 
appear in the pop-up menu. 

This object does not support the 
print operation. The Print item will 
not appear in the pop-up menu. 

This object cannot be dragged by 
the user. 

This object is not visible. The record 
for this object is placed in an open 
folder but is filtered so it is invisible. 

The settings view is not supported 
by this object. 

This object cannot be renamed by 
the user. 

This object cannot have other 
objects dropped on it. (Use 
OBJSTYLE_NODROPON in Warp.) 

Use this instead of 
OBJSTYLE_NODROP (Warp only). 

Use this instead of 
OBJSTYLE_NOTDEFAULTICON 
(Warp only). 
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ulStyleMask - input 

The mask of flags indicating which styles specified in ulStyleFlags will be 
added and which will be removed. For example, if ulStyleFlags is OBJ- 
STYLE NODELETE I OBJSTYLE TEMPLATE and ulStyleMask is OBJ- 
STYLE_NODELETE, the OBJSTYLE_NODELETE flag will be added 
to the style of this object and the OBJSTYLETEMPLATE flag will be 
removed. The valid flags for this parameter are the same as those for 
ulStyleFlags. 

RETURNS 

TRUE—The call was successful. 

FALSE-—An error occurred. 

HOWTO CALL 

Call this method on any object to change its style. This method should 
be used instead of wpSetStyle because it affects only those styles speci¬ 
fied in ulStyleFlags. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

WinCreateObject -9, WinSetObjectData -22, wpclsNew -71, 
wpCreateAnother -47, wpFilterPopupMenu -193, wpQueryStyle -118, 
wpSetStyle -121, wpSetup -63 

NOTES 

The styles of an object can also be set with a setup string passed to func¬ 
tions or methods that support this parameter. See Appendix A for a list 
of keyname value pairs for setup strings. 

Many of the object styles affect whether or not certain pop-up 
menu items appear for an object. For example, OBJSTYLEJNfO- 
DELETE prevents the Delete item from appearing. It is better to set 
the style on the object than to just filter the corresponding item in the 
wpFilterPopupMenu override. 

RESTRICTIONS/WARNINGS 

© The style OBJSTYLE NOSETTINGS has no effect in OS/2 release 
2.1 and earlier. This was fixed in version 2.11. 
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SAMPLE CODE 

The following sample demonstrates how to call wpModifyStyle. This 
method can be called at any time on any Workplace object from either 
a function or a method override. In this example, the variable Object 
is of the type SOMAny * and is assumed to have already been set to a 
valid object pointer. 

/* make this object visible and prevent the user from renaming it */ 
_wpModifyStyle(object, OBJSTYLE_NOTVISIBLE | OBJSTYLE_NORENAME, 

OBJ STYLE_NORENAME) ; 


# wpQueryConfirmatfons WPObJect instance method 

Returns the user action confirmations set for an object. 

SYNTAX 

ULONG wpQueryConfirmations ( ) 

PARAMETERS 

none 


RETURNS 

Constant _Description 


CONFIRM_DELETE 

0x01 

Confirm the deletion of this 
object. 

CONFIRM_DELETEFOLDER 

0x02 

Confirm folder deletion. This is 
ignored if this is not a folder. 

CONFIRMJRENAME 

FILESWITHEXT 

0x04 

Confirm the renaming of this 
object if it has an extension. 

CONFIRMJKEEPASSOC 

0x08 

Confirm the renaming of data 
files with extensions that are 
associated with an application. 

CONFIRM_ACTION 

0x10 

Confirm copy, move, and create 
shadow operations. 

CONFIRM_PROGRESS 

0x20 

Show the progress dialog for 
copy, move, or create shadow 
operations. 
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HOWTO CALL 

Call this method on any object to query its confirmation flags. Query 
the delete confirmation flags of an object before deleting it to check if 
the user wishes to be notified. The default behavior in WPObject for 
this method is to return the user preferences set on the Confirmations 
page of the System object. 

HOWTO OVERRIDE 

Override this method to change the value returned for an object. Call 
the parent method first to get the user preferences and then modify 
the return code. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpConfirmDelete -40, wpDelete -51, wpFree -53 


$ wpQueryCoreRecord WPObject instance 

method (Warp only) 


Returns a pointer to the container record for an object. 

SYNTAX 

PMINIRECORDCORE wpQueryCoreRecord ( ) 

PARAMETERS 

none 

RETURNS 

A pointer to the container record for the object. Do not free this memory. 

HOWTO CALL 

Call this method on any object to access its container record directly. 
Call wpCnrSetEmphasis instead to change any of the record’s empha¬ 
sis attributes. 


HOWTO OVERRIDE 

This method should not be overridden. 
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OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpCnrSetEmphasis -107 


® wpQueryDetaiSsData WPObJect instance method 


Returns the details data of an object. 

SYNTAX 

ULONG wpQueryDetailsData (PVOID *ppDetailsData, PULONG pep ) 

PARAMETERS 

ppDetailsData - input 

This pointer contains a pointer to a buffer that was allocated by the sys¬ 
tem for this object. If it is non-NULL, cast *ppDetailsData to the type de¬ 
fined for your class’ details data and fill in the information for this par¬ 
ticular instance. If this parameter is NULL, put the required size in pep. 
pep - input 

The size of the details data buffer. If ppDetailsData is set to NULL, re¬ 
turn the size required for this object’s details data in pep. 

RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

HOWTO CALL 

This method is only called by the system to get an object’s details data 
when it is awakened. This data is used for the Details view of the ob¬ 
ject’s folder and can be used for sorting or the Include page. 

HOWTO OVERRIDE 

Override this method to provide the details data for instances of your 
subclass. This is only necessary if you have overridden wpclsQuery- 
Detailslnfo and are supporting details view columns for your subclass. 
Call the parent method first. If ppDetailsData is non-NULL, once the de¬ 
tails information is placed in *ppDetailsData, change *ppDetailsData so 
that it points one byte afteryour data in memory. This must be done to 
enable subclasses to write their data in the appropriate place. The data 
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written must be in the same format as the information specified in 
wpclsOueryDetailsInfo. When calculating the size, *pcp, add the size 
of your data to the value already entered by the parent class. See the 
sample code (pg. 138) for more information on overriding this 
method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpCnrRefreshDetails -106, wpclsOueryDetailsInfo -123 

NOTES 

Call wpCnrRefreshDetails (Warp only) on an object to cause the sys¬ 
tem to refresh its details information. This should be done from within 
any application-defined method that sets instance data used in a de¬ 
tails column. 

RESTRICTIONS/WARNINGS 

m The system will call this method when an object is awakened or to re¬ 
fresh the details data of an object. However, in versions before Warp, 
there is no public method for causing an object’s details to be re¬ 
freshed. The WPFileSystem class supports details view data and will 
periodically refresh the details data of its objects. If your class is a de¬ 
scendant of WPFileSystem and you wish to have the details data re¬ 
freshed, call one of the file system methods that changes details 
data. For example, calling wpSetAttr will cause wpQueryDetailsData 
to be called for that object. 

SAMPLE CODE 

See the details data implementation sample at the end of this chapter 
(pg. 138). 


# wpQuerylcon WFObject instance method 

Returns the handle for the icon representing an object. 

SYNTAX 

HPOINTER wpQuerylcon ( ) 
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PARAMETERS 

none 

RETURNS 

(nonzero value)—The handle to the icon for this object. 
NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method at any time to obtain the handle for the icon of an ob¬ 
ject. 

HOWTO OVERRIDE 

This method does not need to be overridden to change the icon for an 
object. Override wpclsQuerylconData to specify the default icon data 
for the class. Call wpSetlconData and then wpSaveDeferred to perma¬ 
nently change the icon data and wpSetlcon to temporarily change the 
icon handle of a specific object. 

OTHER INFO 

Include file: wpobject.h and pmwin.h 

SEE ALSO 

wpclsQuerylconData -124, wpclsSetlcon -130, wpclsSetlconData -130, 
wpQuerylconData -115, wpSaveDeferred -94, wpSetlcon -119, 
wpSetlconData -120 


® wpQuerylconData WPObJect instance method 


Returns the data for the icon representing an object. 

SYNTAX 

ULONG wpQuerylconData (PICONINFO plconlnfo ) 

PARAMETERS 

plconlnfo - input/output 

A pointer to an ICONINFO structure (pg. 136) containing the re¬ 
quested icon data. If NULL is specified, the required size for the buffer 
is returned. 
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RETURNS 

(nonzero value)—The size of the icon data for this object. 
NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method at any time to obtain the icon data for an object. 
Different classes will return icon data in different formats. The 
WPProgram class will return the format ICON !)AT A and the ICON- 
INFO structure will contain a pointer to the data. If the icon was set by 
the user via the General page of the settings notebook, WPAbstract or 
WPFileSystem will use the format ICON_DATA. WPObject will return 
the icon information returned from wpclsOuerylconData. 

HOWTO OVERRIDE 

This method does not need to be overridden to change the icon for an 
object. Override wpclsOuerylconData to specify the default icon data 
for the class. Call wpSetlconData and then wpSaveDeferred to perma¬ 
nently change the icon data and wpSetlcon to temporarily change the 
icon handle of a specific object. 

OTHER INFO 

Include file: wpobject.h and os2def.h 

SEE ALSO 

wpclsOuerylconData -124, wpclsSetlcon -130, wpclsSetlconData -130, 
wpQuerylcon -114, wpSetlcon -119, wpSetlconData -120 

SAMPLE CODE 

The following sample demonstrates how to call wpQuerylconData. 
This can be done at any time from any method or function. In this ex¬ 
ample, the variable Object is assumed to be a valid SOMAny * instance 
pointer. 

ULONG ulSize; 

PICONINFO plconlnfo; 


ulSize = _wpQueryIconData(Object, NULL); 
if (ulSize) 

plconlnfo = ( PICONINFO) _wpAHocMem (Object, ulSize, NULL) ; 
if (plconlnfo) 
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_wpQueryIconData(Object, plconlnfo); 

/* access the data here. */ 

/* and then free it when done */ 
_wpFreeMem(Object, (PBYTE) plconlnfo); 

} 


• wpQueryObjectID WPObject instance method 

(Warp only) 


Returns the ID string of an object. 

SYNTAX 

PSZ wpQueryObjectID ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—A pointer to the ID string for this object. Do not free 
this memory. 

NULL—This object does not have an object ID. 

HOWTO CALL 

Call this method on any object to query its object ID. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpSetup -63 

NOTES 

An object ID is a string that uniquely identifies an object. See Chapter 
2 for more information. 
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RESTRICTIONS/WARNINGS 

@ The method, wpSetObjectID (Warp only), does not write the object 
ID to the ini file and, therefore, is not useful. To set the object ID, 
call wpSetup with the OBJECTID keyword. 


• wpQueryStyle WPObJect Instance method 

Returns the style of an object. 

SYNTAX 

EJLONG wpQueryStyle ( ) 

PARAMETERS 

none 

RETURNS 

The current style flags of the object ORed together. See wpModify- 
Style for a list of object style flags. 

HOWTO CALL 

Call this method at any time to obtain the current styles of an object. 
Call wpclsQueryStyle to obtain the default style for the class. 

HOWTO OVERRIDE 

This method is generally not overridden. Call the wpModifyStyle 
method to change the style flags of an object. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryStyle -127, wpModifyStyle -108, wpSetStyle -121 


• wpQueryTitle WPObJect Instance method 


Returns the title of an object. 
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SYNTAX 

PSZ wpQueryTitle ( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the object’s title string. Do not free this memory. 

HOWTO CALL 

Call this method at any time to obtain the current title of an object. 
Call wpclsQueryTitle to determine the default title for the class. 

HOWTO OVERRIDE 

This method is generally not overridden. Call the wpSetTitle method 
to change the title of an object. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryTitle -129, wpSetTitle -122 


# wpSetlcon WPObJect instance method 


Sets the handle for the icon representing an object. 

SYNTAX 

BOOL wpSetlcon (HPOINTER hptrNewIcon) 

PARAMETERS 

hptrNewIcon - input 

The icon handle to set for this object. 

RETURNS 

TRUE—The icon was set successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

Call this method at any time to set the icon of an object. Changing the 
icon with wpSetlcon is not a persistent change. To permanently change 
the icon of an object, call wpSetlconData and then wpSaveDeferred. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h and pmwin.h 

SEE ALSO 

wpclsQuerylconData -124, wpclsSetlcon -130, wpclsSetlconData -130, 
wpQuerylcon -114, wpQuerylconData -115, wpSetlconData -120 


• wpSetlconData WPObjject Instance method 


Sets the data for the icon representing an object. 

SYNTAX 

BOOL wpSetlconData (PICONINFO plconlnfo) 

PARAMETERS 

plconlnfo - input 

A pointer to an ICONINFO structure (pg. 136) that contains the in¬ 
formation about the new icon for this object. 

RETURNS 

TRUE—The icon was set successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to change the icon of an object. Changes 
made by this method can be saved with wpSaveDeferred. To temporar¬ 
ily change the icon, call wpSetlcon. 


HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include file: wpobject.h and os2def.h 

SEE ALSO 

wpclsQuerylconData -124, wpclsSetlcon -130, wpclsSetlconData -130, 
wpQuerylcon -114, wpQuerylconData -115, wpSetlcon -119 


# wpSetStyle WPObJect instance method 


Sets the style of an object. 

SYNTAX 

BOOL wpSetStyle (ULONG ulNewStyle) 

PARAMETERS 

ulNewStyle - input 

The new style flags for this object. Multiple style flags can be ORed to¬ 
gether at once. See wpModifyStyle for a list of flags. 

RETURNS 

TRUE—The style was successfully changed. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to change the style of an object. 
However, wpModifyStyle is preferred because it only affects the style 
flags specified. wpSetStyle completely replaces all the style settings with 
ulNewStyle. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryStyle -127, wpModifyStyle -108, wpOueryStyle -118 
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• wpSetTitSe WPObJeet instance method 

Sets the title of an object. 

SYNTAX 

BOOL wpSetTitle (PSZ pszNewTitle) 

PARAMETERS 

pszNewTitle - input 

A pointer to the new title for the object. 

RETURNS 

TRUE—The title was successfully set. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the title for an object. There is no 
limit for the size of the string as long as there is enough memory in the 
system. Workplace will make a copy of the string; therefore, it can be 
freed after the call is made. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryTitle -129, wpQueryTitle -118 


Class Methods 


wpclsQueryDetailsInfo returns the details column information for a 
class (pg. 123). 

wpclsOuerylconData returns the data for the default icon for a class 
(pg. 124). 
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wpclsQuerySetting (Warp) returns a setting from a device object 

(pg. 126). 

wpclsQueryStyle returns the default style for a class (pg. 127). 
wpclsQueryTitle returns the default title for a class (pg. 129). 
wpclsSetlcon (Warp) sets the icon for a class (pg. 130). 
wpclsSetlconData (Warp) sets the icon for a class (pg. 130). 
wpclsSetSetting (Warp) sets the value for a device object setting 

(pg-131). 


• wpcisQueryDetailslnfo WPObject class method 

Returns the details column information for a class. 

SYNTAX 

ULONG wpcisQueryDetailslnfo (PCLASSFIELDINFO *ppClassField- 

Info, PULONG pSize) 


PARAMETERS 

ppClassFieldlnfo - input 

This pointer contains a pointer to a linked list of CLASSFIELDINFO 
structures (pg. 132). Each class defines a node in the linked list for 
every details column that is to be implemented. This memory should 
be allocated and initialized in wpclsInitData; or, a global array of 
CLASSFIELDINFO structures can be used. 
pSize - input 

The sum of the required sizes for the details data buffers defined by 
the class and parent classes. 

RETURNS 

The sum of the number of details columns defined by the class and 
parent classes. 

HOWTO CALL 

This method is only called by the system to obtain the details column 
information for a class and all of the classes in the parent chain. This 
data is used for the Details view of the object’s folder and can be used 
for sorting or the Include page. 
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HOWTO OVERRIDE 

Override this method to provide details data column information for 
your subclass. Call the parent method first. If ppClassFieldlnfo is non- 
NULL, add the CLASSFIELDINFO structures for this class at the end 
of the linked list, * ppClassFieldlnfo. If pSize is non-NULL, add the size of 
the class-defined details data structure to the size already placed in 
*pSize by the parent classes. Return the number of CLASSFIELDINFO 
nodes in the * ppClassFieldlnfo list for this class, plus the number re¬ 
turned when the parent method was called. See the sample code (pg. 
138) for more information on overriding this method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpOueryDetailsData -113 

SAMPLE CODE 

See the details data implementation sample at the end of this chapter 
(pg. 138). 


@ wpcIsQueryleonData WPObject class method 

Returns the data for the default icon for a class. 

SYNTAX 

ULONG wpcIsQueryleonData (PICONINFO plconlnfo) 

PARAMETERS 

plconlnfo - input/output 

A pointer to an ICONINFO structure (pg. 136) containing the requested 
icon data. If NULL is specified, the required size for the buffer is returned. 

RETURNS 

(nonzero value)—The size of the icon data for this class. 

0—An error occurred. 

HOWTO CALL 

Call this method at any time to obtain the icon data for a class. This 
method is called by the system to determine the default icon for objects. 
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HOWTO OVERRIDE 

Override this method to specify the default icon data for your class. If 
plconlnfo is NULL, just return the required size for the data. If the 
ICON_DATA format will be used, include the size of the 
pIconInfo->pIconData buffer as well. If plconlnfo is non-NULL, fill in 
the icon data for the class and return the total size. If the data in 
plconlnfo will be in the ICON_DATA format, set pIconInfo->pIconData 
to (PVOID) (plconlnfo+l). You do not need to call the parent method. 

OTHER INFO 

Include file: wpobject.h and os2def.h 

SEE ALSO 

wpclsSetlcon -130, wpclsSetlconData -130, wpQuerylcon -114, 
wpQuerylconData -115, wpSetlcon -119, wpSetlconData -120 

SAMPLE CODE 

The following sample demonstrates how to override wpclsOuerylcon- 
Bata for the class MyClass. The most straightforward way to implement 
this override is using the ICON_RESOURCE format. 

SOM_Scope ULONG SOMLINK mclsM_wpclsQueryIconData(M_MyClass *somSelf, 

PICONINFO plconlnfo) 

{ 

PSZ pszPathName; 

HMODULE hmod; 
somld idClass; 

idClass = SOM_IdFromString("MyClass"); 

pszPathName = _somLocateClassFile( SOMClassMgrObject, 

idClass, 

MyClass_Maj orVersion, 
MyClass_MinorVersion); 

SOMFree(idClass) ; 

DosQueryModuleHandle( pszPathName, &hmod); 


/* test if plconlnfo is NULL in case this call is just to query 
the size */ 
if (plconlnfo) 

{ 

plconlnfo->cb = sizeof(ICONINFO); 
p!conInfo->fFormat = ICON_RESOURCE; 
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plconlnfo->pszFileName = OL; 

plconlnfo->hmod = hmod; // module in which to find the 

// resource 

plconlnfo->resid = 1000; // resource id for the icon 

plconlnfo->cbIconData = OL; 
plconlnfo->pIconData = NULL; 

} /* endif */ 

return sizeof(ICONINFO); 


# wpcIsQyerySettirig WPAbstract class 

method (Warp only) 


Returns a setting from a device object. 

SYNTAX 

ULONG wpclsQuerySetting (PSZ pszSetting, PVOIB pValue, ULONG 

ulValueLen) 


PARAMETERS 

pszSetting - input 

A pointer to a string containing the name of the setting to query. See 
Appendix F for a list of device objects that support this method as well 
as the setting strings they have defined. 
pValue - input/output 

A pointer to the buffer that will hold the returned setting. If set to 

NULL, the required size is returned. 

ulValueLen - input 

The size of the pValue buffer. 

RETURNS 

(nonzero value)—The size of the data for this setting. 

0—An error occurred and no data was returned. 

HOWTO CALL 

Call this method at any time to query a setting for a WPAbstract subclass. 

HOWTO OVERRIDE 

WPAbstract subclasses can override this method to provide their own 
settings values. Check the pszSetting parameter, and if it is not a string 
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defined by your subclass, call the parent method. Otherwise, check 
ulValueLen to be sure the buffer is the correct size, place the setting 
value in pValue, and return the size of the data. 

OTHER INFO 

Include file: wpabs.h 

SEE ALSO 

wpclsSetSetting -131 


• wpdsQueryStyle WPObJect class method 

Returns the default style for a class. 

SYNTAX 

ULONG wpdsQueryStyle ( ) 

PARAMETERS 

none 

RETURNS 

The current class style flags of the class ORed together. The following 
class styles correspond to the object styles that are used as the default 
style for all objects of this class: 

Constant Corresponding object style 


CLSSTYLE_NEVERMOVE 

0x02 

OBJSTYLE_NOMOVE 

CLSSTYLE_NEVERLINK 

0x04 

OBJSTYLE_NOLINK 

CLSSTYLEJNEVERCOPY 

0x08 

OBJSTYLE_NOCOPY 

CLSSTYLE_NEVERDELETE 

0x40 

OBJSTYLE_NODELETE 

CLSSTYLE_NEVERPRINT 

0x80 

OBJSTYLE_NOPRINT 

CLSSTYLE_NEVERDRAG 

0x100 

OBJSTYLE_NODRAG 

CLSSTYLE_NEVERVISIBLE 

0x200 

OBJSTYLE_NOTVISIBLE 


CLSSTYLE_NEVERTEMPLATE (or CLSSTYLE_DONTTEMPLATE in Warp) 
prevents the user from making an object a template. The Template 
checkbox is removed from the General page of the settings notebook and 
default templates are not created in the Templates folder for the class._ 



128 


Workplace Shell 


CLSSTYLE_PRIVATE (or CLSSTYLE HIDDEN in Warp) prevents the class 
from being displayed in class lists in the user interface (for example, the 
Find dialog). 

HOWTO CALL 

Call this method at any time to obtain the default styles for a class. 

HOWTO OVERRIDE 

Override this method to change the default styles for a class. Call the 
parent first and store the return code. Take out or add any flags from 
the parent’s returned styles. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpModifyStyle -108, wpQueryStyle -118, wpSetStyle -121 

NOTES 

Call wpModifyStyle to change the style flags of an individual object. 

RESTRICTIONS/WARNINGS 

• When an object is created, wpclsOueryStyle is called to query the de¬ 
fault styles for the object. This information is stored in the persistent 
instance data of the object, and wpclsOueryStyle is not called again 
for this object. If the class implementation is then modified and the 
class default style changes, it will not affect objects that have already 
been created. 

m The default styles of the parent of your class may not be desirable. 
For example, the WPAbstract class, by default, has CLSSTYLE_NEV- 
ERTEMPLATE. After creating the first instance of your class, be sure 
to examine the behavior of the object and change any of the style 
flags in your wpclsOueryStyle override to remove unwanted behav¬ 
ior from the parent class. 

SAMPLE CODE 

The following sample demonstrates an override of wpclsOueryStyle 
from the class MyClass. MyClass is a subclass of WPAbstract but has 
templateable objects. 
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SOM_Scope ULONG SOMLINK melsM_wpclsQueryStyle(M_MyClass *somSelf) 
{ 


/* call the parent method and take out the CLSSTYLE_NEVERTEMPLATE 
flag */ 

return (parent_wpclsQueryStyle(somSelf) 

& ~ CLSSTYLE_NEVERTEMPLATE); 


• wpclsQueryTitle WPObject class method 

Returns the default title for a class. 

SYNTAX 

PSZ wpclsQueryTitle ( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the class’ title string. 

HOWTO CALL 

Call this method at any time to obtain the default title for a class. Do 
not free the returned string. 

HOWTO OVERRIDE 

Override this method to provide the default title for your class. Do not 
call the parent method. The string returned from your override 
should not be freed while the class is loaded. It is easiest to create a 
global variable that is an array of characters and return it from the 
wpclsQueryTitle override. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpQueryTitle -118, wpSetTitle -122 
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• wpcSsSetlcoo WPObJect class method (Warp only) 

Sets the default icon for a class. 

SYNTAX 

BOOL wpclsSet!con(HPOINTER hptrNewIcori) 

PARAMETERS 

hptrNewIcon - input 

The icon handle to set for this class. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the default icon for a class. This 
change is only temporary and will only last until the class is unloaded. 
Usually it is best to override wpclsQuerylconData instead of calling this 
method. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQuerylconData -124, wpclsSetlconData -130, wpQuerylcon -114, 
wpQuerylconData -115, wpSetlcon -119, wpSetlconData -120 


% wpclsSetlconData WPObJect class method (Warp only) 


Sets the default icon for a class. 

SYNTAX 

BOOL wpclsSetlconData(PICONINFO plconlnfo) 
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PARAMETERS 

plconlnfo - input 

A pointer to an ICONINFO structure (pg. 136) containing the icon 
data to set on the class. flFormat must be ICON_RESOURCE. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the default icon for a class. This 
change is only temporary and will only last until the class is unloaded. 
Usually it is best to override wpclsOuerylconData instead of calling this 
method. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQuerylconData -124, wpclsSetlcon -130, wpQuerylcon -114, 
wpQuerylconData -114, wpSetlcon -119, wpSetlconData -120 


# wpdsSetSetting WPAbstract class method (Warp only) 


Sets the value for a device object setting. 

SYNTAX 

BOOL wpdsSetSetting (PSZ pszSetting, PVOID pValue) 

PARAMETERS 

pszSetting - input 

A pointer to a string containing the name of the setting. See Appendix 
F for a list of device objects that support this method as well as the set¬ 
ting strings they have defined. 
pValue - input 

A pointer to the buffer that contains the data to set. 
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RETURNS 

TRUE—The value was set successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set a settings value for a WPAbstract 
subclass. 

HOWTO OVERRIDE 

WPAbstract subclasses can override this method to provide their own 
settings values. Check the pszSetting parameter, and if it is not a string 
defined by your subclass, call the parent method. Otherwise, change 
the value of the specified setting to the new value passed in pValue. 

OTHER INFO 

Include file: wpabs.h 

SEE ALSO 

wpclsQuerySetting -126 


General Object Settings: Structures 

CLASSFIELDINFO (80) 

cb (ULONG) 0 

The size of the structure, in bytes, including cb itself. 

flData (ULONG) 4 

Attributes of the field’s data. This is the same as the flData field in the FIELDINFO structure 
for container details view. OR together multiple flags to specify the attributes of the data dis¬ 
played in a column. 

Constant_ Description _ 


CFA_ 

LEFT 

0x001 

Left align the text. 

CFA 

RIGHT 

0x002 

Right align the text. 

CFA 

CENTER 

0x004 

Center the text. 
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CFA_TOP 

0x008 

Top align the text. 

CFA_VCENTER 

0x010 

Vertically center the text. 

CFAJBOTTOM 

0x020 

Bottom align the text. 

CFAJNVISIBLE 

0x040 

Make this column invisible. 

CFA_BITMAPORICON 

0x100 

Data is a bitmap or an icon handle. 

CFA_SEPARAT OR 

0x200 

A vertical separator will be placed to 
the right of this data. 

CFAJHORZSEPARATOR 

0x400 

A horizontal separator will be placed 
below this data. 

CFA_STRING 

0x800 

Data is a pointer to a string of charac¬ 
ters. 

CFA_OWNER 

0x1000 

Ownerdraw field. 

CFA_DATE 

0x2000 

Data is a pointer to a CDATE structure. 

CFAJTIME 

0x4000 

Data is a pointer to a CTIME structure. 

CFA_FIREAD ONLY 

0x8000 

Column is read-only. 

CFA_FITITLE 

READONLY 

0x10000 

Column title is read-only (use this flag 
for flTitle). 

CFA_ULONG 

0x20000 

Column is in number format. 


flTitle (ULONG) 8 

Attributes of the field’s title. This is the same as the flTitle field in the FIELDINFO structure 

for container details view. OR together multiple flags to specify the attributes of the title for 
a column. See flData for a list of flags. 

pTitleBata (PVOID) 12 

The title data. The flTitle flags specify what type of data this is. 

ulReserved (ULONG) 16 

Reserved by the system. Set to 0. 

pUserBata (PVOID) 20 

Pointer to optional user data. 

pNextFieldlnfo (PCLASSFIELDINFO) 24 

Pointer to the next CLASSFIELDINFO structure in the linked list. 


cxWidth (ULONG) 

The width of the field in pixels. Can be 0. 


28 
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offFieldData (ULONG) 32 

Offset from the beginning of this class’ data for this field. For example, if the class defines 
the following details data: 

typedef struct _MYDETAILS 
{ 

PSZ pszString; 

ULONG ulNumber; 

} MYDETAILS; 

in the following CLASSFIELDINFO array, offFieldData would be filled in as 

CLASSFIELDINFO ClassFieldlnfo<[>2]; 

ClassFieldlnfo[0].offFieldData = FIELDOFFSET(MYDETAILS, pszString); 
ClassFieldlnfo[1].offFieldData = FIELDOFFSET(MYDETAILS, ulNumber); 

Note: The order of the field definition structures in the linked list must be the same as 
the order of fields in the details data structure. 

ulLenFieldData (ULONG) 36 

The size of the details data in bytes. Using the sample example for offFieldData, 

ClassFieldlnfo[0].ulLenFieldData = sizeof(PSZ); 

ClassFieldlnfo[1].ulLenFieldData = sizeof(ULONG); 

pfnOwnerDraw (PFNOWNDRW) 40 

The ownerdraw procedure for this column. Can be NULL unless CFA_OWNER was speci¬ 
fied for this column. PFNOWNDRW functions should be defined as follows: 

BOOL EXPENTRY OwnerDrawFunc(HWND hwnd, PVOID Paraml, PVOID Param2); 

hwnd is the handle of the window to be painted. Paraml is a pointer to an OWNERITEM struc¬ 
ture used for owner draw containers. Param2 is a pointer to the value to draw. This is NULL ex¬ 
cept when this function is called to paint details displayed in the Include criteria dialog. 

Return TRUE if the field was ownerdrawn and FALSE if the container control should 
do the default painting. 

flCompare (ULONG) 44 

The following flags can be ORed together to specify the sort and include attributes for this field: 

Constant Description 

COMPARE_SUPPORTED 0x01 These values can be used with comparison 

functions to support the Include and Sort 
page. 

SORTBY_SUPPORTED 0x02 This column can be used to sort the folder 

views. 
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pfnCompare (PFNCOMPARE) 48 

Comparison function for this field. This value allows you to specify your own function to be 
called when two values for this details column are compared for sort or include support. Set 
to NULL if COMPARE_SUPPORTED was not specified in the flCompare flags. Compare 
functions should be defined as follows: 


LONG EXPENTRY CompareValues(PVOID Paraml, PVOID Param2); 


Paraml is a pointer to the details field value. Param2 is a pointer to the value to be com¬ 
pared with. 

Return one of the following values: 

Constant 


Description 

CMPJEQUAL 

0 

The two values are equal. 

CMP_GREATER 

1 

Paraml is greater than Param2. 

CMP_LESS 

2 

Paraml is less than Param2. 


DefaultComparison (ULONG) 52 

The default compare operator in the include page add/change criteria dialog. 


Constant ___ Description 


CMPJEQUAL 

0 

Show the object if it is equal to the 
compare value. 

CMP_GREATER 

1 

Show the object if it is greater than 
the compare value. 

CMPJJESS 

2 

Show the object if it is less than the 
compare value. 

CMP_GREATER_OR_EQUAL 

3 

Show the object if it is greater than 
or equal to the compare value. 

CMP_LESS_OR_EQUAL 

4 

Show the object if it is less than or 
equal to the compare value. 

CMP_NOT_EQUAL 

5 

Show the object if it is not equal to 
the compare value. 


ulLenCompareValue (ULONG) 56 

Maximum length of the compare data. This must be filled in if COMPARE_SUPPORTED is 
specified in flCompare. 

pDefCompare Value (PVOID) 60 

The default value for comparisons in the Include page criteria Add/Change dialog. Can be 
NULL unless ownerdraw is used for this column. 
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pMmCompareValue (PVOID) 64 

The minimum compare value. This value will be used to set the limits of the spin button for 
CFAJLLONG details data on the Include page criteria Add/Change dialog. Can be NULL. 

pMaxCompareValue (PVOID) 68 

The maximum compare value. This value will be used to set the limits of the spin button for 
CFAJLLONG details data on the Include page criteria Add/Change dialog. Can be NULL. 

pszEditControlClass (PSZ) 72 

A pointer to a string containing the name of the class for a user-defined edit control. The 
support for user-defined edit controls for the Include page Add/Change criteria dialog cur¬ 
rently does not work. Therefore, this field should be set to NULL and flCompare should be 
zero if this column is CFA_OWNER. 

pfnSort (PFNCOMPARE) 76 

The function for this field used to sort data from this column. This value can be NULL. See 
pfnCompare for a description of an FNCOMPARE function. 

Note: If you specify SORTBY_SUPPORTED in the flCompare flags and the type of data 
for this column is CFAJLLONG, the default sort behavior is to sort numbers in descending 
order. You must provide a sort function for this column if you want your values to sort in as¬ 
cending order. 

Used by: wpclsQueryDetailsInfo -123 


ICONINFO 

v'V-.,:/';'> - ■ "V ■ 








cb (ULONG) 0 

The size in bytes of the ICONINFO structure including cb itself. 

fFormat (ULONG) 4 

The format of the data contained in the ICONINFO structure. Specify one of the following: 


Constant 


Description 


ICONJFILE 1 This icon data is a file name, and pszFileName 

contains the fully qualified path of an .ico file. 

ICONJRESOURCE 2 This icon data is an icon resource, hmod con¬ 

tains the module name, and resid contains the 
resource ID for this icon. 
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ICON_DATA 

3 This icon data is in raw data format. cblconData 

contains the size of the icon data, and pIconData 
points to the bitmap data for this icon. 

ICON_CLEAR 

4 Set flFormat to ICON_CLEAR when calling 

wpSetlconData to have the object’s icon revert 
back to its default. If the object is a WPProgram, 
it will use the icon for the executable the object 
refers to. 


pszFileName (PSZ) 8 

The fully qualified path of a .ico file. This value is ignored if flFormat is not ICON_FILE. 

hmod (HMODULE) 12 

The handle for the module that contains the icon resource specified by resid. This value is 
ignored if flFormat is not ICON_RESOURCE. 

resid (ULONG) 16 

The ID for the icon resource contained in hmod. This value is ignored if flFormat is not 
ICONJRESOURCE. 

cblconData (ULONG) 20 

This size of the icon data that pIconData points to. This value is ignored if flFormat is not 
ICON_DATA. 

pIconData (PVOID) 24 

A pointer to the bitmap data for this icon. This value is ignored if flFormat is not 
ICONJDATA. 

Used by: wpclsQuerylconData -124, wpclsSetlconData -130, wpQuerylconData -115, 
wpSetlconData -120 


POINTL 









x (LONG) 

The x coordinate for a point, 
y (LONG) 

The y coordinate for a point. 

Used by: wpCnrlnsertObject -233, wpQueryNextlconPos -251 
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Details Data Sample Code 


The following sample demonstrates how to implement details data for 
an object class. The relevant code from the .C and .H files for the class 
MyClass have been included. The class methods are shown before the 
instance methods to make this easier to follow. 

From the .h file: 

HMODULE hmod; // handle of the class .DLL Set in wpclsInitData... 

#define MAXSTRING 256 

#define NUM_DETAILS_FIELDS 2 // number of details view columns for 

// this class 

CLASSFIELDINFO MyClassFieldlnfo<[>NUM_DETAILS_FIELDS]; //Details 

//column 
//definitions 

/* below is the class specific details data. MyClassFieldlnfo is an 
array of 

* structures that define the columns. The class only has ONE 
definition 

* structure. Each object will have extra memory to hold a 
MYCLASSDATA structure. 

* This structure is filled in for each object in the 
wpQueryDetailsData override. 

*/ 

typedef struct _MYCLASSDATA 

{ 

PSZ pszComment; //will point to _pszComment instance data 

ULONG ulHandle; //the object handle. Not very useful data 

//but demonstrates numeric details data. 

} MYCLASSDATA, *PMYCLASSDATA; 

LONG EXPENTRY CompareHandles(PVOID Paraml, PVOID Param2); 

LONG EXPENTRY CompareStrings(PVOID Paraml, PVOID Param2); 

MRESULT EXPENTRY EditControlProc(HWND hwnd, ULONG msg, MPARAM mpl, 
MPARAM mp2); 

/* the following three ULONGs are used to define the Handles details 


data */ 


ULONG 

ulMinValue = 

0; 

// 

the 

minimum 

value 

for 

comparison 

criteria 

ULONG 

ulMaxValue = 

5; 

// 

the 

maximum 

value 

for 

comparison 

criteria 

ULONG 

ulDefValue = 

3; 

// 

the 

default 

value 

for 

comparison 

criteria 



General Object Settings 


139 


From the .c file: 

#undef SOM_CurrentClass 
#define SOM_CurrentClass SOMMeta 


/* override wpclsInitData to initialize the global MyClassFieldlnfo 
array and set the hmod global variable. 

*/ 

SOM_Scope void SOMLINK mclsM_wpclsInitData(M_MyClass *somSelf) 

{ 

PSZ pszPathName; 

PCLASSFIELDINFO plnfo; 
somld idClass; 

parent_wpclsInitData(somSelf); 
idClass = SOM_IdFromString("MyClass"); 

pszPathName = _somLocateClassFile( SOMClassMgrObject, 

idClass, 

MyClass_Maj orVersion, 
MyClass_MinorVersion); 

SOMFree(idClass) ; 

DosQueryModuleHandle( pszPathName, &hmod); 

/* Setup the MyClassFieldlnfo array. Use the plnfo pointer to make 
* referencing easier. 

*/ 


/* point plnfo to the first item in the MyClassFieldlnfo array which 

* is the Comment column. The structures in this array must be in the 

* same order as the fields in the MYCLASSDATA structure that they 

* represent. 

*/ 

plnfo = MyClassFieldlnfo; 

/* zero out the structure */ 

memset((PCH) plnfo, 0, sizeof(CLASSFIELDINFO)); 
pInfo->cb = sizeof(CLASSFIELDINFO); 

/* the data in this column will be a string so use CFA_STRING*/ 
plnfo->flData = CFA_RIGHT | CFA_SEPARATOR | CFA_FIREADONLY | 


CFA_STRING; 



140 


Workplace Shell 


plnfo->flTitle = CFA_CENTER I C FA_S EPARATOR I CFA_HORZ S E PARATOR I 
CFA_STRING I CFA_FITITLEREADONLY; 

/* plnfo+l is the next field info structure in the array */ 
plnfo->pNextFieldInfo = plnfo+l; 
plnfo->pTitleData = "Comment"; 

plnfo->fICompare = COMPARE_SUPPORTED I SORTBY_SUPPORTED; 
plnfo->offFieldData = FIELDOFFSET(MYCLASSDATA, pszComment); 
plnfo->ulLenFieldData = sizeof(PSZ); 
plnfo->DefaultComparison = CMP_EQUAL; 

plnfo->pfnCompare = CompareStrings; // provide a user-defined compare 

// function 

plnfo->pfnSort = CompareStrings; // use the same function for sort 
plnfo->ulLenCompareValue = MAXSTRING; // this value is required. 

/* point plnfo to the next field info structure */ 
pInfo++; 

memset((PCH) plnfo, 0, sizeof(CLASSFIELDINFO)); 
plnfo->cb = sizeof(CLASSFIELDINFO); 

/* the data for this column is numeric so use CFA_ULONG */ 
plnfo->flData = CFA_RIGHT I CFA_SEPARATOR I CFA_FIREADONLY I 
CFA_ULONG; 

plnfo->flTitle = CFA_CENTER I CFA_SEPARATOR I CFA_HORZSEPARATOR I 
CFA_STRING I CFA_FITITLEREADONLY; 
plnfo->pNextFieldInfo = NULL; 
plnfo->pTitleData = "Handle"; 

plnfo->fICompare = COMPARE_SUPPORTED I SORTBY_SUPPORTED; 

plnfo->offFieldData = FIELDOFFSET(MYCLASSDATA, ulHandle); 

plnfo->ulLenFieldData = sizeof(ULONG); 

pInfo->ulLenCompareValue = sizeof(ULONG); 

plnfo->DefaultComparison = CMP_EQUAL; 

pInfo->pfnCompare = CompareHandles; 

plnfo->pfnSort = CompareHandles; 

plnfo->pMinCompareValue = (PVOID)&ulMinValue; 

plnfo->pMaxCompareValue = (PVOID)kulMaxValue; 

plnfo->pDefCompareValue = (PVOID)&ulDefValue; 

} 

/* override wpclsQueryDetailsInfo to add the field info structures 
* for this class to the linked list. 

*/ 
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SOM_Scope ULONG SOMLINK mclsM_wpclsQueryDetailsInfo(M_MyClass* somSelf, 

PCLASSFIELDINFO 
*ppClassFieldInfo, 
PULONG pSize) 

{ 

ULONG ulNumColumns, i; 

PCLASSFIELDINFO plnfo; 

/* call the parent class FIRST */ 
ulNumColumns = parent_wpclsQueryDetailsInfo 

(somSelf,ppClassFieldlnfo,pSize); 

/* if the pSize pointer is set, add the size of our class specific 

* data to the size already specified by the parent classes. 

*/ 

if (pSize) 

*pSize = *pSize + sizeof(MYCLAS SDATA); 

/* if the ppClassFieldlnfo pointer is set, put our details info 

* structures at the end of the linked list. 

*/ 

if (ppClassFieldlnfo) 

{ 

if (^ppClassFieldlnfo) 

{ 

plnfo = ^ppClassFieldlnfo; 

/* loop through the ppClassFieldlnfo list and find the end */ 
for (1=1; i < ulNumColumns; i++) 

{ 

if (plnfo->pNextFieldInfo) 

plnfo = pInfo->pNextFieldInfo; 

} 

/* plnfo now points to the end. Set its next pointer to the 

* first node in our list (MyClassFieldlnfo). Note that when we 

* initialized this structure in wpclsInitData, we already set 

* the next pointers of the nodes. 

*/ 

plnfo->pNextFieldInfo = MyClassFieldlnfo; 

} 

else 

/* there are no fields in the list. Put ours at the head. */ 
^ppClassFieldlnfo = MyClassFieldlnfo; 
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/* return the number of columns returned from the parent classes 
plus the number 
* defined by this class. 

*/ 

return(ulNumColumns + NUM_DETAILS_FIELDS); 

} 

#undef SOM_CurrentClass 

#define SOM_CurrentClass SOMInstance 

/* override wpQueryDetailsData to fill in the details information for 
* a specific instance of this class. 

*/ 

SOM_Scope ULONG SOMLINK mcls_wpQueryDetailsData(MyClass *somSelf, 

PVOID *ppDetailsData, 
PULONG pep) 

{ 

PMYCLASSDATA pMyDetails; 

MyClassData *somThis = MyClassGetData(somSelf) ; 

/* call the parent method first */ 

parent_wpQueryDetailsData(somSelf,ppDetailsData,pep); 

/* if ppDetailsData is set, it has already been modified by the 
* parent class to point to where our data must be written. 

*/ 

if (ppDetailsData) 

{ 

/* point pMyDetails to where the data will be written and fill 
* in the details data. 

*/ 

pMyDetails = (PMYCLASSDATA) *ppDetailsData; 
pMyDetails->pszComment = _pszComment ? _pszComment : NULL; 
pMyDetails->ulHandle = _wpQueryHandle(somSelf); 

/* point ppDetailsData to location after my data */ 
^ppDetailsData = ((PBYTE) (^ppDetailsData)) + 
sizeof(MYCLASSDATA); 

} 

if (pep) 

/* add the size of the buffer to *pcp */ 

*pcp += sizeof(MYCLASSDATA); 
return(TRUE); 


} 
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#undef SOM_CurrentClass 

/* CompareHandles is the sort and include page comparison function 

* for the ulHandle details data. It is not necessary to provide a 

* compare function but in this case, sort will by default sort 

* numbers in descending order unless a sort function is provided. 
*/ 

LONG EXPENTRY CompareHandles(PVOID Paraml, PVOID Param2) 

{ 

ULONG ulValue, ulCompare; 

ulValue = *((PULONG)Paraml); 
ulCompare = *((PULONG)Param2); 

if (ulValue < ulCompare) 
return(CMP_LESS); 
else if (ulValue == ulCompare) 
return(CMP_EQUAL); 

else 

return(CMP_GREATER); 

} 

/* CompareStrings is the sort and include page comparison function 

* for the pszComment details data. It is not necessary to provide 

* a compare function for string data, (it is here for 

* demonstration purposes) 

*/ 

LONG EXPENTRY CompareStrings(PVOID Paraml, PVOID Param2) 

{ 

PSZ pszValue, pszCompare; 

LONG lRet; 

pszValue = (PSZ) Paraml; 
pszCompare = (PSZ) Param2; 

lRet = stricmp(pszValue, pszCompare); 
if (lRet < 0) 
return(CMP_LESS); 
else if (lRet > 0) 
return(CMP_GREATER); 
else 

return(CMP_EQUAL); 
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E ach Workplace object has an in-use list defined by the WPObject 
class. The in-use list is a linked list of USEITEM (pg. 154) struc¬ 
tures that contain information on resources currently in use by the 
object. When an object opens a view, allocates memory, is added to a 
container view, opens an association, or has awakened shadows, the 
system will add an item to the in-use list which can later be accessed 
by calling wpFindUseltem. It is the programmer’s responsibility 
to add USAGE_OPENVIEW use items to the in-use list, using 
wpAddToObjUseList, whenever an application-defined view is created. 
The system then uses this information to place hash marks on the ob¬ 
ject’s icon, to switch to existing views, and to close views of an object 
when it is deleted. 

The USEITEM structures are always followed immediately in 
memory by structures specific to the type of item. When adding an 
item to the in-use list, allocate the USEITEM structure and the type 
specific structures together to ensure that they will follow one another 
in memory. 
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Restrictions and Warnings 

• Applications cannot define new USEITEM structure types. Only the 
predefined USAGE_* constants are acceptable. 


Instance Methods 


wpAddToObjUseList adds an item to the in-use list of an object 
(pg. 145). 

wpDeleteFromObjUseList removes an item from the in-use list of an 
object (pg. 148). 

wpFmdUseltem finds an item in the in-use list of an object 
(pg. 150). 

wpFmdViewItem (Warp) finds a VIEWITEM in the in-use list of an ob- 
ject. (pg. 152). 


® wpAddToObjUseList WPObJect instance method 


Adds an item to the in-use list of an object. 

SYNTAX 

BOOL wpAddToObjUseList (PUSEITEM pUseltem) 

PARAMETERS 

pUseltem - input 

The address of the USEITEM (pg. 154) to be added to the in-use list. 
A type dependent structure must immediately follow the USEITEM 
structure in memory. Do not free pUseltem after calling this method, as 
the system does not make a copy of the memory that pUseltem points to. 

RETURNS 

TRUE—The item was successfully added to the in-use list. 

FALSE—An error occurred. 
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HOWTO CALL 

Call this method on any object to add an item to the in-use list. The sys¬ 
tem will lock the object once if the type of use item is USAGE_RECORD, 
USAGEJLINK, or USAGE_OPENVIEW. Applications that define new 
views for objects should add USAGEOPENVIEW items to the in-use list 
when the view is created. These items should be removed with the 
wpDeleteFromObjUseList method when the view closes. 

HOWTO OVERRIDE 

It is not generally necessary to override this method in a Workplace ap¬ 
plication, but it can be used as a notification of when items are added 
to the in-use list. Be sure to call the parent method. Use a wpOpen 
override instead for notification when a view is opened. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAllocMem -80, wpCreateShadowObject -50, 

wpDeleteFromObjUseList -148, wpFindUseltem -150, wpOpen -160, 
wpSwitchTo -173 

NOTES 

wpAddToObjUseList is predominantly called by applications to add 
USAGE_OPENVlEW items to the in-use list. Other types of USEITEM 
structures can be added when applicable, but are usually added by the 
system. The system will call this method to add a USAGE_LINK item 
when a shadow is created or to add USAGE_MEMORY items when 
memory is allocated with wpAllocMem. USAGE_RECORD items are 
added for an object each time it is added to a container, and US- 
AGE_OPENFILE items are added for a data file when it opens a pro¬ 
gram as its view. 

RESTRICTIONS/WARNINGS 

• The memory for the type-dependent structure must immediately 
follow that of the USEITEM structure; therefore, they should be al¬ 
located together. 

SAMPLE CODE 

The following sample demonstrates how to add an item to the in-use 
list. In this example, a USAGE_OPENVIEW use item is added from the 
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window procedure itself. The item could also have been added from 
the wpOpen override, but it is easier for the window procedure to keep 
track of the use item so it can be removed from the in-use list when the 
view is closed. 

typedef struct 

{ 

SOMAny ^Object; 

USEITEM Useltem; //note that Useltem and Viewltem are next to 
//each other 
VIEWITEM Viewltem; 

} DLGDATA, * PDLGDATA; 

#define OPEN_HELLO OPEN_USER 

This view is a dialog that was loaded using WinLoadDlg, and the 
WM_INITDLG processing from the dialog procedure is shown below: 

case WM_INITDLG: 

{ 

SOMAny *Object; 

PDLGDATA pDlgData; 

/* somSelf was passed to the dialog when it was loaded */ 

Object = (SOMAny *) mp2; 

pDlgData = (PDLGDATA) _wpAllocMem(Object, sizeof(DLGDATA), NULL); 
if (pDlgData) 

{ 

/* hwndDlg is the HWND parameter of this dialog window 
procedure */ 

WinSetWindowULong(hwndDlg, QWL_USER, (ULONG) pDlgData); 
memset(pDlgData, 0, sizeof(DLGDATA) ); 

pDlgData->Object = Object; 

/* for convenience, the Useltem and Viewltem structures are 
part of the window words. 

*/ 

pDlgData->UseItem.type = USAGE_OPENVIEW; 
pDlgData->ViewItem.view = OPEN_HELLO; 

pDlgData->ViewItem.handle = hwndDlg; // hwndDlg is the frame 
_wpAddToObjUseList(Object, &pDlgData->UseItem); 

} 



148 


Workplace Shell 


else 

/* Data allocation failed. Destroy the dialog. 
WinDestroyWindow(hwndDlg); 

} 

return(MRESULT) FALSE; 


• wpOeleteFromObfUseList WPObJect instance method 


Removes an item from the in-use list of an object. 

SYNTAX 

BOOL wpDeleteFromObjUseList (PUSEITEM pUseltem) 

PARAMETERS 

pUseltem - input 

The address of the USEITEM (pg. 154) to be removed from the in-use 
list. 

RETURNS 

TRUE—The item was successfully removed from the in-use list. 

FALSE—The item was not found or an error occurred. 

HOWTO CALL 

Call this method on any object to remove an item from its in-use list. 
The system will unlock the object once if the type of use item is US- 
AGE_RECORD, USAGE JLINK, or USAGE_OPENVIEW. Applications 
that add use items using wpAddToObjUseList should call this method 
to remove them when they are no longer valid. 

HOWTO OVERRIDE 

If a view was defined by a parent class, overriding wpDeleteFrom¬ 
ObjUseList and checking for USAGE_OPENVIEW items is a good no¬ 
tification for when these views are closed. Be sure to call the parent 
method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAddToObjUseList -145, wpFindUseltem -150, wpFreeMem -82 
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RESTRICTIONS/WARNINGS 

® When wpDeleteFromObjUseList is called, the system does not free 
the memory that was used for the item removed. It is the applica¬ 
tion’s responsibility to free this memory. 

SAMPLE CODE 

The following sample demonstrates how to remove an item from the 
in-use list. In this example, it is removed from within the dialog’s win¬ 
dow procedure of the object’s view. The same dialog is used in the sam¬ 
ple for wpAddToObjUseList. 

typedef struct 

{ 

SOMAny ^Object; 

USEITEM Useltem; //note that Useltem and Viewltem are next to 
//each other 
VIEWITEM Viewltem; 

} DLGDATA, * PDLGDATA; 

The following is the WM_DESTROY processing in the dialog win¬ 
dow procedure: 

case WM_DESTROY: 

{ 

PDLGDATA pDlgData; 

/* hwndDlg is the window handle parameter for this dialog window 
procedure */ 

pDlgData = (PDLGDATA) WinQueryWindowULong(hwndDlg, QWL_USER); 
if (pDlgData) 

{ 

/* remove the use item from the in-use list */ 
_wpDeleteFromObjUseList(pDlgData->Object, &pDlgData->Use!tem); 


/* free the dialog data */ 

_wpFreeMem(pDlgData->Object, (PBYTE) pDlgData); 


} 

break; 
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• wpFiodUseltem WPObject instance method 

Finds an item in the in-use list of an object. 

SYNTAX 

PUSEITEM wpFindUseltem (ULONG type, PUSEITEM pCurrentltem) 

PARAMETERS 

type - input 

The type of the USEITEM to find. Valid types are as follows: 


Define 


Description 

USAGE_MEMORY 

1 

Usually added by wpAllocMem and is 
followed by a MEMORYITEM structure. 

USAGEJRECORD 

4 

Added when the object is placed in a 
container and is followed by a RECORDITEM 
structure. 

U SAGE_OPENVIEW 

5 

Added when a view of an object is opened 
and is followed by a VIEWITEM structure. 

USAGE_LINK 

6 

Added when a shadow of an object is created 
and is followed by a LINKITEM structure. 

USAGE_OPENFILE 

20 

Added when a data file opens a program and 
is followed by a VIEWFILE structure. 


The definition of USEITEM and all the item-specific structures are 
at the end of this chapter. 
pCurrentltem -input 

The address of an item in the list after which to start the search. If 
NULL, the search will start with the first item in the list. 

RETURNS 

(nonzero value)—The pointer to the use item found. 

NULL—No item of the type specified by ulType was found or 
pCurrentltem was not in the list. 

HOWTO CALL 

Call this method to enumerate items of a specific type in the in-use list. 
Do not use the pNext pointer in the USEITEM structure to traverse 
the in-use linked list. 



In-Use List 


151 


HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpAddToObjUseList -145, wpDeleteFromObjUseList -148, 
wpFindViewItem -152 

NOTES 

This method is extremely useful for obtaining information about 
which views are currently open for an object or which shadows of an 
object are currently awake. 

SAMPLE CODE 

The following sample shows how to use the wpFindUseltem method to 
get information about currently open views of an object. The function 
QueryOpenViews returns the number of open views for an object. 

ULONG QueryOpenViews(WPObject ^Object) 

{ 

PUSEITEM pCurrent; 

ULONG ulCount = 0; 

/* use a for loop to find all the open views for this object */ 

for (pCurrent - _wpFindUseItem(Object, USAGE_OPENVIEW, NULL); 
pCurrent; 

pCurrent = _wpFindUseItem(Object, USAGE_OPENVIEW, pCurrent) ) 

{ 

/* One was found. Increment the count. */ 


ulCount++ ; 

} 


return(ulCount); 


} 
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• wpFindViewItem WPObject instance 

method (Warp only) 


Finds a VIEWITEM in the in-use list of an object. 

SYNTAX 

PVIEWITEM wpFindViewItem (ULONG flViews, PVIEWITEM 

pCurrentltem) 


PARAMETERS 

flViews - input 


The types of views 
gether: 

Define 

to search for. The following flags can be ORed to- 

Deseription 

VIEW_CONTENTS 

0x01 

Icon view for folders. 

VIEW_SETTIN GS 

0x02 

Settings view. 

VIEW_RUNNIN G 

0x08 

Program view for programs and 
program files. 

VIEWJDETAILS 

0x10 

Details view for folders. 

VIEW_TREE 

0x20 

Tree view for folders. 

VIEW_ANY 

OxFFFFFFFF 

Any view. 


pCurrentltem - input 

The address of a VIEWITEM (pg. 155) in the list after which to start the 
search. If NULL, the search will start with the first item matching 
flViews. Note: this value is a VIEWITEM not a USEITEM. 

RETURNS 

(nonzero value)—The pointer to the VIEWITEM found. 

NULL—No VIEWITEM for the views specified in flViews was found. 

HOWTO CALL 

Call this method to find a VIEWITEM in the in-use list. wpFindUse- 
Item can also be used to find VIEWITEM structures. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpFindUseltem -150 


fn-Use List: Structures 


LINKITEM _(4 bytes) 


LinkObj (WPObject *) 0 

The WPShadow object this use item represents. 

Used by: wpAddToObjUseList-145, WpDeleteFromObjUseList-148, wpFindUseltem -150 


MEMORYIITEM (4 bytes) 

cbBuffer (ULONG) 0 

The number of bytes in the memory block this use item represents. The memory directly 
follows this structure. 

Used by: wpAddToObjUseList-145, wpDeleteFromObjUseList-148, wpFindUseltem -150 


RECORDITEH _(>2 bytes) 


hwndCnr (HWND) 0 

The container the object has been inserted into. 

pRecord (PMINIRECORDCORE) 4 

The container record representing this object. 

ulUser (ULONG) 8 

For application use. 

Used by: wpAddToObjUseList -145, wpDeleteFromObjUseList -148, wpFindUseltem -150 



154 


Workplace Shell 


USE1TEM 


(8 bytes) 

type (ULONG) 

The type of this use item. 


0 

Define 


Description 

USAGEJMEMORY 

1 

Usually added by wpAllocMem and is fol¬ 
lowed by a MEMORYITEM structure. 

USAGE_RECORD 

4 

Added when the object is placed in a con¬ 
tainer and is followed by a RECORDITEM 
structure. 

U SAGE_OPENVIEW 

5 

Added when a view of an object is opened 
and is followed by a VTEWITEM structure. 

USAGE_LINK 

6 

Added when a shadow of an object is created 
and is followed by a LINKITEM structure. 

U SAGE_OPENFILE 

20 

Added when a data file opens a program and 
is followed by a VIEWFILE structure. 


pNext (PUSEITEM) 4 

Pointer to the next use item. Use wpFindUseltem instead of referencing this pointer di¬ 
rectly. 

Used by: wpAddToObjUseList -145, wpDeleteFromObjUseList -148, wpFindUseltem -150 


VIEWFILE 




ulMenuId (ULONG) 0 

The menu ID if this is an association or an item from the menu page. 

handle (LHANDLE) 4 

The handle for the open view. This is the HAPP of the program started with WinStartApp. 

hwndCnr (HWND) 8 

Reserved for system use only. 

pRecord (PMINIRECORDCORE) 12 

Reserved for system use only. 

Used by: wpAddToObjUseList-145, wpDeleteFromObjUseList-148, wpFindUseltem -150 
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(20 bytes) 


view (ULONG) 0 

The identifier of the view this use item represents. See Appendix E for a list of predefined 
views. 


handle (LHANDLE) 4 

The handle for the open view. For OPEN_RUNNING, this is the HAPP of the program 
started with WinStartApp. For other predefined views, this is an hwnd. 


ulViewState (ULONG) 

View state flags: 


8 

Define 

Description 


VIEWSTATE_OPENING 

0x01 

The view is being opened. 

VIEWSTATE_OBJECTDELETED 

0x02 

The object is being deleted. 

VIEWSTATE_U SERHIDDEN 

0x04 

The view was hidden by the 



user. 

VTEWSTATE_POPULATIN G 

0x08 

The view is populating. 

hwndCnr (HWND) 

Reserved for system use only. 


12 

pRecord (PMINIRECORDCORE) 


16 


Reserved for system use only. 

Used by: wpAddToObjUseList -145, wpDeleteFromObjUseList -148, wpFindUseltem 
-150, wpFindViewItem -152 




A view allows the user to interact with an object. For example, the 
WPFolder class provides icon, tree, and details views to show the 
contents of a folder, and the WPPalette class provides the palette view 
to display the palette itself. Each object has a settings view that displays 
its properties and allows the user to alter them. Most available views are 
listed in the Open pulldown of the pop-up menu. (In Warp, the 
Settings view menu item was moved to the top level menu.) When the 
user selects a view to open from a pop-up menu or double-clicks on an 
object, the system calls the wpViewObject method. 

Many Workplace Shell classes have predefined views listed in 
Appendix E, and application developers can define new views for their 
subclasses. Each view is represented by a numeric value, and applica¬ 
tions must define their views using values greater than or equal to 
OPENJUSER. If you wish to change the behavior of a view already de¬ 
fined by your parent class or process one of your application-defined 
views, override wpOpen. All Workplace views, once opened, must be 
registered with the system and added to the object’s in-use list with 
wpRegisterView and wpAddToObjUseList respectively. It is the respon¬ 
sibility of the programmer to call these two methods when an applica¬ 
tion-defined view is opened. 
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Registering a View with Workplace 

When a Workplace Shell object opens a view, the wpRegisterView 
method should be called to notify the system to register the view. When 
a view is registered, it will be placed in the window list and subclassed 
by the shell to provide pop-up menu support from the system menu. 
The system will also change the title of the opened view window to in¬ 
clude the name of the view. 

The In-Use List 

wpAddToObjUseList must be called to add a USAGE_OPENVIEW item 
to the in-use list whenever a view is created. This will put hash marks on 
the object’s icon and ensure that the object will not go dormant while 
the view is open. This also enables the shell to switch to the view when 
the object is double-clicked on by the user or when wpSwitchTo is 
called. (See Chapter 6 for more information about in-use lists.) 

The Default View 

The default view is the view opened when the user double-clicks on the 
object, when the Open conditional cascade in the pop-up menu is se¬ 
lected without opening its pulldown, or when wpOpen is called with 
OPENJDEFAULT as the ulView parameter. When the WPObject class 
processes the wpModifyPopupMenu method, the menu item for the 
default view is given a check mark in the Open pulldown of the pop-up 
menu. Users set the default view of a WPFileSystem descendant via the 
Menu page; applications can set and query this value for any object us¬ 
ing wpSetDefaultView and wpQueryDefaultView respectively. 

Restrictions and Warnings 

t> When the system places a check mark next to the default view in the 
Open pulldown of the pop-up menu, it assumes the menu item IDs 
for application-defined views are the same as their corresponding 
view constants. 

<$ When defining a new view and adding it to the in-use list for an ob¬ 
ject, if you do not set the handle field in the VIEWITEM structure to 
be an HWND, you must override wpSwitchTo to provide the func¬ 
tionality for that view. 
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instance Methods 


wpClose closes all views of an object (pg. 158). 
wpHide hides all views of an object (pg. 159). 
wpOpen opens a view of an object (pg. 160). 

wpQueryButtonAppearance returns the type of minimize button for 
an object’s views (pg 162). 

wpQueryConcurrentView returns the view open behavior of an object 
(pg. 164). 

wpQueryDefaultView returns the default view of an object 
(pg. 165). 

wpQueryMinWindow returns the behavior of the minimize button for 
an object’s views (pg. 166). 

wpRegisterView registers a view with the system (pg. 167). 
wpRestore restores all views of an object (pg. 168). 
wpSetButtonAppearance sets the type of minimize button for an ob¬ 
ject’s views (pg. 169). 

wpSetConcurrentView sets the view open behavior of an object (pg. 
170). 

wpSetBefaultView sets the default view of an object (pg. 171). 
wpSetMinWindow sets the behavior of the minimize button for an ob¬ 
ject’s views (pg. 172). 

wpSwitchTo switches to an open view of an object (pg. 173). 
wpViewObject opens a view of an object (pg. 174). 
wpWaitForClose (Warp) pauses a thread until the specified view is 
closed (pg. 176). 


® wpClose WPObJect instance method 

Closes all views of an object. 

SYNTAX 

BOOL wpClose ( ) 

PARAMETERS 


none 
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RETURNS 

TRUE—The views were successfully closed. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to close all of its views. 

HOWTO OVERRIDE 

Overriding this method will not provide notification each time a view 
is closed by the user. This method is only called by the system when an 
object is closed as a result of a workarea folder closing or when an ob¬ 
ject is deleted. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpHide -159, wpOpen -160, wpRestore -168 


® wpHide WPObjject instance method 

Hides all views of an object. 

SYNTAX 

BOOL wpHide ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The views were successfully hidden. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to hide all of its views. 
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HOWTO OVERRIDE 

Overriding this method will not provide notification each time a view 
is hidden by the user. This method is only called by the system when an 
object is hidden as a result of a workarea folder hiding or minimizing. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpClose -158, wpOpen -160, wpRestore -168 


© wpOpen WPObject instance method 


Opens a view of an object. 

SYNTAX 

HWND wpOpen (HWND hwndCnr , ULONG ulView , ULONG param) 

PARAMETERS 

hwndCnr - input 

The window handle for the container from which this object is 
opened. This can be set to NULLHANDLE. The system usually sets this 
parameter when the user opens an object. 
ulView - input 

The numeric value that represents the view to open. See Appendix E 
for a list of predefined Workplace Shell views. Application-defined 
views must be greater than or equal to OPEN_USER. 
param - input 

An application-defined parameter for the view. For predefined 
Workplace views, this value should be NULLHANDLE. 

RETURNS 

(nonzero value)—The handle for the opened view. 

NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method on any object to open a view. In most cases, it is 
preferable to call wpViewObject. wpOpen will open the view regardless 
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of whether a view is already opened. However, wpViewObject will 
query the object’s open behavior and first call wpSwitchTo. 
wpViewObject eventually calls wpOpen. 

HOWTO OVERRIDE 

Override this method to open an application-defined view or to 
change the behavior of an existing view. Whenever an object’s view is 
opened, this method is called. Call the parent method to open any 
views not defined by your subclass. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpClose -158, wpclsQueryDefaultView -178, wpHide -159, 
wpOneryDefau 1 tView -165, wpRegisterView -167, wpRestore -168, 
wpSetDefaultView -171, wpSwitchTo -173, wpViewObject -174 

NOTES 

It is not necessary to check if a view of the same type is already opened 
from the override of wpOpen. When the user opens an object, the sys¬ 
tem calls wpViewObject which checks for open views and then calls 
wpOpen. Providing this functionality in the wpOpen method would be 
duplicate code. 

SAMPLE CODE 

The following sample demonstrates how to call wpOpen to open the 
Icon view of the System Setup folder. 

SOMAny *Folder; 


/* get the object pointer for the system setup folder */ 

Folder = _wpclsQueryFolder(_WPObject, "<WP_CONFIG>", TRUE); 
if (Folder) 

{ 

/* open the folder and unlock the object because we are through 
with it */ 

_wpOpen(Folder, NULLHANDLE, OPEN_CONTENTS, 0); 

_wpUnlockObject(Folder); 


} 
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# wpQueryButtoriAppearanee WPObJect 

instance method 


Returns the type of minimize button for an object’s views. 

SYNTAX 

ULONG wpQueryButtonAppearance( ) 

PARAMETERS 

none 

RETURNS 

Define Description 

HIDEBUTTON 1 Use a hide button instead of minimize. 

MINBUTTON 2 Use a minimize button. 

DEFAULTBUTTON 3 Use the return from wpclsQueryButtonAppearance. 


HOWTO CALL 

Call this method on any object before opening a view to determine the 
type of minimize button to use. The user chooses this setting on the 
Window page of the settings notebook. 

HOWTO OVERRIDE 

Override this method to temporarily change the response an object 
has to this method. Call wpSetButtonAppearance to permanently 
change the button appearance of an object’s views. Override 
wpclsQueryButtonAppearance to change the class default. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

somGetClass -395, wpclsQueryButtonAppearance -177, wpOpen -160, 
wpSetButtonAppearance -169 

NOTES 

The Settings view of an object always has a hide button regardless of 
the object’s button appearance setting. 
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The default value for an object is DEFAULTBUTTON; therefore, 
the object will always use the class default unless wpSetButton- 
Appearance is called to change the value. 

SAMPLE CODE 

The following sample demonstrates how to use wpQueryButton- 
Appearance. It is a code snippet from a function called OpenView 
which could be called by the wpOpen override when the application- 
defined view is requested: 

HWND OpenView(SOMAny *Object) 

{ 

ULONG ulButtonAppearance; 

ULONG ulFrameFlags = FCF_TITLEBAR I FCF_SYSMENU I FCF_SIZEBORDER 
I FCF_ICON I FCF_SHELLPOSITION; 

HWND hwndFrame; 

/* The parameter, Object, passed into this function is the 
* pointer of the object passed into the wpOpen override. 

*/ 

ulButtonAppearance = _wpQueryButtonAppearance(Object); 

/* If this object uses the class default, query the default 
appearance for the class. 

*/ 

if (ulButtonAppearance == DEFAULTBUTTON) 
ulButtonAppearance = 

_wpclsQueryButtonAppearance(_somGetClass(Object)); 

if (ulButtonAppearance == HIDEBUTTON) 
ulFrameFlags 1= FCF_HIDEMAX; 
else 

ulFrameFlags 1= FCF_MINMAX; 

/* Now you are ready to create the frame with the correct frame 
control flags. 

*/ 


return(hwndFrame); 


} 
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• wpQyeryCoocurreritVSew WPObJect instance method 

Returns the view open behavior of an object. 

SYNTAX 

ULONG wpQueryConcurrentView( ) 

PARAMETERS 

none 

RETURNS 


Define 


Description 

CCVTEW_DEFAULT 

0 

Use the system default. 

CCVIEW_ON 

1 

Open a new view each time it is requested by 
the user. 

CCVIEW_OFF 

2 

Open a new view only if none yet exist. 


HOWTO CALL 

Call this method on any object to determine its view open behavior. 
The user chooses this setting on the Window page of the settings note¬ 
book. Call wpclsQuerySetting (Warp only) on the WPSystem class to 
determine the system default (see Appendix F). 

HOWTO OVERRIDE 

Override this method to temporarily change the response an object 
has to this method. Call wpSetConcurrentView to permanently change 
the object’s view open behavior. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQuerySetting -126, wpOpen -160, wpSetConcurrentView -170, 
wpViewObject -174 
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NOTES 

The wpViewObject method will call wpQueryConcurrentView to de¬ 
termine whether to try to switch to an existing view of the same type 
before calling wpOpen. 


® wpQueryDefauItView WPObJect instance method 

Returns the default view of an object. 

SYNTAX 

ULONG wpQueryDefaultView( ) 

PARAMETERS 

none 

RETURNS 

The default view for this object. See Appendix E for a list of predefined 
views. 

HOWTO CALL 

Call this method on any object to determine its default view. 

HOWTO OVERRIDE 

Override this method to temporarily change the response an object 
has to this method. Call wpSetDefaultView to permanently change the 
default view for this object. Override wpclsQueryDefaultView to 
change the class default. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryDefaultView -178, wpOpen -160, wpSetDefaultView -171, 
wpViewObject -174 

NOTES 

The wpViewObject and wpOpen methods will call this method if 
OPENJDEFAULT is the requested view. 
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@ wpQueryMinWindow WPObJect instance method 

Returns the behavior of the minimize button for an object’s views. 

SYNTAX 

ULONG wpQueryMinWindow( ) 

PARAMETERS 

none 

RETURNS 

The behavior of the minimize button for any view of this object: 


Define 


Description 

MINWIN_DEFAULT 

0 

Use the system default behavior for minimized 
windows. 

MINWIN_HIDDEN 

1 

Hide the window. 

MINWNJVIEWER 

2 

Minimize the window to the Minimized 

Window Viewer. 

MINWIN_DESKTOP 

3 

Minimize the window to the Desktop. 


HOWTO CALL 

Call this method to query the behavior of the minimize button for an 
object’s views. Call wpclsQuerySetting (Warp only) on the WPSystem 
class to determine the system default behavior (see Appendix F). 

HOWTO OVERRIDE 

Override this method to temporarily change the response an object 
has to this method. Call wpSetMinWindow to permanently change the 
minimize button behavior for this object. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQuerySetting -126, wpQueryButtonAppearance -162, 
wpSetMinWindow -172, wpSetButtonAppearance -169 
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NOTES 

The system calls this method when the view of an object is minimized 
by the user. If the view has a hide button instead of a minimize button, 
the view will always hide and this method is not called. 


® wpRegisterView WPObject instance method 

Registers a view with the system. 

SYNTAX 

BOOL wpRegisterView(HWND hwndFrame, PSZ pszViewTitle ) 

PARAMETERS 

hwndFrame - input 

The frame window handle for this view. 
pszViewTitle - input 
The title for this view. 

RETURNS 

TRUE—The view was registered successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to register its view with the system. 
Applications that define new views should call this method when the 
view is opened. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobjecth 

SEE ALSO 

wpOpen -160 
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NOTES 

When this method is called, the system will change the title of 
hwndFrame to be the object title followed by the view name specified in 
pszViewTitle. 

RESTRICTIONS/WARNINGS 

m A view that is registered does not need the FCF_TASKLIST frame 
control flag because Workplace will put the view in the window list. 
m The window handle passed to wpRegisterView must be a frame win¬ 
dow. Note that the window handle passed into a dialog window pro¬ 
cedure is the frame, but the window handle passed into a standard 
window procedure is the client. To get the frame handle from the 
client, call WinOueryWindow on the client passing QWJPARENT. 


® wpRestore WPObject instance method 

Restores all views of an object. 

SYNTAX 

BOOL wpRestore ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The views were successfully restored. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to restore all of its views. 

HOWTO OVERRIDE 

Overriding this method will not provide notification each time a view 
is restored by the user. This method is only called by the system when 
an object is restored as a result of a workarea folder being restored. 

OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpClose -158, wpHide -159, wpOpen -160, wpSwitchTo -173 

NOTES 

When a view is restored, the window is returned to its original size, be¬ 
fore it was minimized or hidden. 


® wpSetButtonAppearance WPObfect instance method 

Sets the type of minimize button for an object’s views. 

SYNTAX 

VOID wpSetButtonAppearance(ULONG ulButtonType ) 

PARAMETERS 

ulButtonType - input 

The type of minimize button to use. 


Define 


Description 

HIDEBUTTON 

1 

Hides the window when pressed by the user. 

MINBUTTON 

2 

Minimizes the window when pressed by the user. 

DEFAULTBUTTON 

3 

Uses the default returned from 



wpclsQueryButtonAppearance. 


RETURNS 

none 

HOWTO CALL 

Call this method on any object to set its minimize button appearance. 
If the hide button is used, the views will always hide when it is pressed. 
However, if a minimize button is used, the button will function ac¬ 
cording to the value returned from wpQueryMinWindow. The user 
chooses this setting on the Window page of the settings notebook. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsQueryButtonAppearance -177, wpQueryButtonAppearance -162, 
wpQueryMin Window -166 

NOTES 

The Settings view of an object always has a hide button regardless of 
the object’s button appearance setting. 


• wpSetConcurrentView WPObject instance method 

Sets the view open behavior of an object. 

SYNTAX 

VOID wpSetConcurrentView(ULONG ulCCView ) 

PARAMETERS 

ulCCView - input 

The concurrent view behavior: 


Define 


Description 

CCVIEW_DEFAULT 

0 

Use the system default. 

CCVIEW_ON 

i 

Open a new view each time it is requested by the 

user. 

CCVIEW_OFF 

2 

Open a new view only if none yet exist. 


RETURNS 

none 

HOWTO CALL 

Call this method on any object to set its view open behavior. The user 
chooses this setting on the Window page of the settings notebook. Call 
wpclsSetSetting (Warp only) on the WPSystem class to set the system 
default behavior (see Appendix F). 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsSetSetting -131, wpQueryConcurrentView -164 

NOTES 

The wpViewObject method will call wpQueryConcurrentView to de¬ 
termine whether to try to switch to an existing view of the same type 
before calling wpOpen. 


• wpSetDefauItView WPObject instance method 


Sets the default view of an object. 

SYNTAX 

BOOL wpSetDefaultView ( ULONG ulView) 

PARAMETERS 

ulView - input 

The new default view for this object. See Appendix E for a list of possi¬ 
ble views. Do not set this parameter to OPEN_DEFAULT. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any object to change its default view. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobjecth 
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SEE ALSO 

wpclsQueryDefaultView -178, wpOpen -160, wpQueryDefaultView -165, 
wpViewObject -174 

NOTES 

The wpViewObject and wpOpen methods will query this value with 
wpQueryDefaultView if OPEN_DEFAULT is the requested view. 


9 wpSetMinWindow WPObject instance method 

Sets the behavior of the minimize button for an object’s views. 

SYNTAX 

VOID wpSetMinWindow (ULONG ulMinWindow) 

PARAMETERS 

ulMinWindow - input 

The behavior of the minimize button for any view of this object: 


Define 


Description 

MINWIN_DEFAULT 

0 

Use the system default behavior for minimized 
windows. 

MINWIN_HIDDEN 

1 

Hide the window. 

MINWN_VIEWER 

2 

Minimize the window to the Minimized Window 

Viewer. 

MINWINJDESKTOP 

3 

Minimize the window to the Desktop. 


RETURNS 

none 

HOWTO CALL 

Call this method to set the behavior of the minimize button for an ob¬ 
ject’s views. This does not apply to views with a hide button. Call 
wpclsSetSetting (Warp only) on the WPSystem class to set the system 
default behavior (see Appendix F). 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpclsSetSetting -131, wpOueryButtonAppearance -162, 
wpQueryMinWindow -166, wpSetButtonAppearance -169 

NOTES 

The system calls wpQueryMinWindow when the minimize button of a 
view is pressed by the user. 


# wpSwitcfiTo WPObJect Instance method 

Switches to an open view of an object. 

SYNTAX 

BOOL wpSwitchTo (ULONG View) 

PARAHETERS 

View - input 

The numerical value that represents the view to switch to. See 
Appendix E for a list of Workplace Shell predefined views. 

RETURNS 

TRUE—A view of this type was successfully found and brought to the 
foreground. 

FALSE—No views of this type were found or an error occurred. 

HOWTO CALL 

Call this method on any object to bring a previously opened view to the 
foreground. The system will search for the first USAGEJVIEW item in 
the in-use list corresponding to the specified view. If this method is 
called and the view is not yet opened, it will return FALSE. If an open 
view is desired, call wpViewObject instead. wpViewObject will first call 
wpSwitchTo to find an existing view and then call wpOpen if a new 
open view is needed. 
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HOWTO OVERRIDE 

This method should only need to be overridden to process applica¬ 
tion-defined views that are added to the in-use list by setting the han¬ 
dle field in the VIEWITEM structure to something other than an 
HWND. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpClose -158, wpHide -159, wpOpen -160, wpRestore -168, 
wpYiewObject -174 


• wpYiewObject WPObJect instance method 


Opens a view of an object. 

SYNTAX 

HWND wpViewObject (HWND hwndCnr , ULONG ulView , EJLONG 
param) 

PARAMETERS 

hwndCnr - input 

The window handle for the container from which this object is 
opened. This can be set to NULLHANDLE. The system usually sets this 
parameter when the user opens an object. 
ulView - input 

The numerical value that represents the view to open. See Appendix E 
for a list of predefined Workplace views. 
param - input 

Application-defined parameter for the view. For predefined Workplace 
views, this value should be NULLHANDLE. 

RETURNS 

(nonzero value)—The handle for the opened view. 

NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method on any object to open a view. Calling this method is 
preferred over calling wpOpen directly. 
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HOWTO OVERRIDE 

Override this method to change its behavior, but do not use this over¬ 
ride to process the opening of application-defined views; wpOpen 
should be overridden for that purpose. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpClose -158, wpclsQueryDefaultView -178, wpHide -159, 
wpOpen -160, wpQueryDefaultView -165, wpRegisterView -167, 
wpRestore -168, wpSetDefaultView-171, wpSwitchTo -173 

NOTES 

The WPObject class processes this method first by checking the con¬ 
current view behavior of the object with wpQueryConcurrentView. If 
concurrent views are allowed, wpOpen is called, passing the same pa¬ 
rameters that were passed to wpViewObject. If concurrent views are 
not allowed, an existing view is searched for with wpSwitchTo. If 
wpSwitchTo then returns FALSE, wpOpen is called. The net effect is 
that a view of the requested type is brought to the foreground. 

SAMPLE CODE 

The following sample demonstrates how to call wpViewObject by 
opening the Icon view of the System Setup folder. 

SOMAny *Folder; 


/* get the object pointer for the system setup folder */ 

Folder = _wpclsQueryFolder(_WPObject, "<WP_CONFIG>", TRUE); 
if (Folder) 

{ 

/* open the folder and unlock the object because we are through 
with it */ 

_wpViewObject(Folder, NULLHANDLE, OPEN_CONTENTS, 0); 
_wpUnlockObject(Folder) ; 
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• wpWaitForClose WPObJect Instance 

method (Warp only) 


Pauses a thread until the specified view is closed. 

SYNTAX 

ULONG wpWaitForClose (LHANDLE IhView, ULONG ulViews, LONG 

ITimeOut , BOOL bAutoClose) 


PARAMETERS 

IhView - input 

The window handle or HAPP of the view to wait for. If NULLHANDLE 
is specified, this method will use the ulViews parameter. 
ulViews - input 

The numerical value that represents the type of view to wait for. This 
method will wait until all views of this type have closed. See Appendix 
E for a list of predefined Workplace views. This parameter is used only 
if IhView is NULLHANDLE. 

ITimeOut - input 

The maximum time to wait before returning. 
bAutoClose - input 

When set to TRUE, the system will close the specified view(s), if still 
open. 

RETURNS 

0—The method completed successfully. 

-1—An error occurred. 

Otherwise—The return code from WinWaitEventSem. 

HOWTO CALL 

Call this method from a separate thread to block until a view of an ob¬ 
ject has closed. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 


wpclsQueryButtoiiAppearance returns the default type of the mini¬ 
mize button for views (pg. 177). 

wpclsQueryDefaultView returns the default view for a class 
(pg. 178). 

wpclsQueryObjectFromFrame (Warp) returns the pointer to the ob¬ 
ject that owns a specified view’s frame window (pg. 179). 


® wpdsQueryButtonAppearaiice WPObJect class method 

Returns the default type of minimize button for views. 

SYNTAX 

ULONG wpclsQueryButtonAppearance( ) 

PARAMETERS 

none 

RETURNS 

Define 

HIDEBUTTON 
MINBUTTON 

HOWTO CALL 

Call this method on any class object to determine the default button 
appearance of that class. 

HOWTO OVERRIDE 

Override this method to provide the class default button appearance. 
The WPObject class object will respond to this method by returning 
the value set on the Window page of the System object. 


Description 

1 Use a hide button. 

2 Use a minimize button. 


OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpOpen -160, wpOueryButtonAppearance -162, 
wpSetButtonAppearance -169 

NOTES 

The Settings view of an object always has a hide button regardless of 
the object’s button appearance setting. 

SAMPLE CODE 

See the sample for wpOueryButtonAppearance which also shows when 
to use wpclsOueryButtonAppearance. 


• wpelsQueryDefauItView WPObJeet class method 


Returns the default view for a class. 

SYNTAX 

ULONG wpelsQueryDefauItView ( ) 

PARAMETERS 

none 

RETURNS 

The default view for this class. See Appendix E for a list of possible views. 
Application-defined views above OPEN_USER can also be returned. 

HOWTO CALL 

Call this method on any class object to determine its default view. 

HOWTO OVERRIDE 

Override this method to provide the class default view. The parent 
method does not have to be called. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpOpen -160, wpOueryDefaultView -165, wpSetDefaultView -171, 
wpViewObject -174 
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RESTRICTIONS/WARNINGS 

m When an object is created, its default view is set to this value. The 
default view of the object is saved and the class method will not be 
called again to determine the class default. Therefore, if the class 
default view is changed by changing the return from wpclsQuery- 
DefaultView, it will not affect objects that have already been cre¬ 
ated. 


$! wpcIsQueryOfoJectFromFrame WPOesktop class 

method (Warp only) 


Returns the pointer to the object that owns a specified view’s frame 
window. 

SYNTAX 

WPObject * wpclsQueryObjectFromFrame (HWND hwndFrame ) 

PARAMETERS 

hwndFrame - input 

The handle of a top-level window. 

RETURNS 

(nonzero value)—The pointer to the object that owns this view. 

NULL—No associated object could be found. 

HOWTO CALL 

Call this method on the Desktop class object, JWPDesktop, to find the 
object associated with a view. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpdesk.h 

SEE ALSO 

wpOpen -160, wpViewObject -174 






Settings 

Notebooks 


A ll Workplace objects inherit the Settings view OPENJSETTINGS 
from the WPObject class. WPObject opens this view by creating a 
notebook using the PM notebook control and calls wpAddSettingsPages 
on the object. Each class overrides wpAddSettingsPages to add its pages 
to the notebook. These pages are dialogs that enable the user to change 
the object’s instance data. To implement a settings notebook page, first 
design a dialog resource using the dialog box editor that comes with the 
OS/2 toolkit and define the corresponding dialog procedure. Then 
override wpAddSettingsPages to call wpInsertSettingsPage and pass the 
required information. 

All settings pages for an object are added to the notebook by 
wpAddSettingsPage each time the Settings view for the object is 
opened. However, the dialog resource for each page is not loaded by 
the system until the user first selects that page. Once a dialog for a 
page has been loaded, it remains as a child of that page until the note¬ 
book is closed. 

All Workplace classes have a method for every page added to the 
settings notebook. If you do not want a specific page to appear in the 
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notebook, override the corresponding method listed in Appendix 
C and return SETTINGS_PAGE_REMOVED. These settings page 
methods can also be called directly from a wpAddSettingsPages over¬ 
ride. 

Restrictions and Warnings 

it> The Workplace classes generally implement the wpAddSettings¬ 
Pages method by passing the BKAJLAST flag to wpInsertSettings- 
Page. This always adds the page to the bottom of the notebook. 

# Verify that your settings page dialog procedure sets the focus on one 
of its controls whenever it returns TRUE from WM_INITDLG. If it 
returns FALSE, the focus will automatically be set for you. Failing to 
ensure that focus is on one of the controls could cause random desk¬ 
top windows to receive the focus as settings pages are turned by the 
user. 


Instance Methods 


wpAddSettingsPages adds pages to an object’s settings notebook 

(pg. 181). 

wpInsertSettingsPage inserts an individual page into the settings note¬ 
book (pg. 183). 


• ¥/pAddSettingsPages WPObJect instance method 

Adds pages to an object’s settings notebook. 

SYNTAX 

BOOL wpAddSettingsPages (HWND hwndNotebook) 

PARAMETERS 

hwndNotebook - input 

The handle of the settings notebook created by the WPObject class. 
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RETURNS 

TRUE—The settings pages were successfully added. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system. If an application 
calls this method, the wpInsertSettingsPage method must be overrid¬ 
den and its functionality must be completely replaced. 

HOWTO OVERRIDE 

Override this method to add pages to the Settings view. Call the parent 
class at any time to allow ancestor classes to add their settings pages as 
well. The system will not open the settings notebook if FALSE is re¬ 
turned from this method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpInsertSettingsPage -183 

SAMPLE CODE 

The following sample demonstrates how to override wpAddSettings- 
Pages to add pages to the settings notebook. 

SOM_Scope BOOL SOMLINK mcls_wpAddSettingsPages(MyClass *somSelf, 

HWND hwndNotebook) 

{ 

PAGEINFO pageinfo; 

BOOL fReturn; 

/* This is a help subtable in memory. The first value is the size 

* in words of each entry. Next are pairs of dialog controls with 

* their corresponding help panel ids. The last entry MUST be 0, 

* 0. A help subtable is only required if you want to implement 

* context sensitive help. 

*/ 

HELPSUBTABLE HelpSubTable [] = { 2, 

IDC_ENTRY / IDHELP_ENTRY, 

IDC_UNDO, IDHELP_UNDO / 

0 , 0 } ; 


fReturn = parent_wpAddSettingsPages(somSelf, hwndNotebook); 
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/* add another settings page here... */ 
memset((PCH)&pageinfo,0,sizeof(PAGEINFO)); 


pageinfo.cb 

= 

sizeof(PAGEINFO); 


pageinfo.hwndPage 

= 

NULLHANDLE; 

// 

use the resource 

pageinfo.usPageStyleFlags 

= 

BKA_MAJ OR; 

// 

major tab 

pageinfo.usPageInsertFlags 

= 

BKA_FIRST; 

// 

add to top of 




// 

notebook 

pageinfo.pfnwp 

= 

MyPageDlgProc; 

// 

window proc 

pageinfo.resid 

= 

hmod; 

// 

.DLL module handle 

pageinfo.dlgid 


IDD_MYPAGE; 

// 

ID of dialog 

pageinfo.pszName 

= 

"~My Page"; 

// 

Tab text 

pageinfo.pCreateParams 

= 

somSelf; 

// 

pass object ptr to 




// 

the dialog 

pageinfo.idDefaultHelpPanel 

= 

RES_MYPAGE; 

// 

resource id of 




// 

general help 

pageinfo.pszHelpLibraryName 

- 

"MYCLASS.HLP" ; 

// 

help library name 

pageinfo.pHelpSubtable 

= 

HelpSubTable; 

// 

help subtable 


if (! _wpInsertSettingsPage( somSelf, hwndNotebook, &pageinfo )) 
fReturn = FALSE; 
return fReturn; 


® wpSosertSettlogsPage WPObJect instance method 

Inserts an individual page into the settings notebook. 

SYNTAX 

IJLONG wpInsertSettingsPage(HWND hwndNotebook, PPAGEINFO 

ppageinfo) 


PARAMETERS 
hwndNotebook - input 

The handle of the settings notebook created by the WPObject class. 
Use the hwndNotebook parameter passed into the wpAddSettingsPages 
override when calling this method. 
ppageinfo - input 

A pointer to a PAGEINFO structure (pg. 187) containing information 
about the page to add. 
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RETURNS 

(nonzero value)—The ID of the page inserted. 

0—An error occurred. 

HOWTO CALL 

This method is only called from an override of wpAddSettingsPages, 
and it should be called once for each page that is to be added to the 
settings notebook. 

HOWTO OVERRIDE 

This method is generally not overridden unless the entire functional¬ 
ity of the Settings view is being replaced. 

OTHER INFO 

Include files: wpobject.h and pmwp.h define: 

INCL_WINWORKPLACE 


SEE ALSO 

wpAddSettingsPages -181, wpclsQuerySettingsPageSize -185 

NOTES 

If a dialog resource ID is passed in the PAGEINFO structure, the sys¬ 
tem will load the dialog when the user turns to that page. 

The system makes a copy of the PAGEINFO structure passed into 
ppageinfo. Therefore, ppageinfo can be freed after the call to this 
method is made. 

SAMPLE CODE 

See the sample for wpAddSettingsPages for an example of how to use 
this method. 


Class Methods 


wpclsQuerySettingsPageSize returns the size of the settings pages for a 
class (pg. 185). 

wpelsSetSettingsPageSize (Warp) sets the size of the settings pages for 
a class (pg. 186) . 
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# wpcSsQuerySettingsPageSize WPObJect class method 


Returns the size of the settings notebook pages for a class. 

SYNTAX 

BOOL wpclsOuerySettingsPageSize(PSIZEL pSizl) 

PARAMETERS 

pSizl - input/output 

A pointer to a SIZEL structure (pg. 189) to be filled with the desired 
size, in dialog units, for the settings notebook pages for this class. 

RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called to query the default settings page size for a 
class. Most applications should have no need to call this method. 

HOWTO OVERRIDE 

Override this method to return the default settings page size for your 
class. The parent method does not need to be called but is useful in de¬ 
termining the maximum size required. The WPObject class processes 
this method by returning the system default size for settings pages. 

OTHER INFO 

Include files: wpobject.h and pmgpi.h 

SEE ALSO 

wpAddSettingsPages -181, wpclsSetSettingsPageSize -186, 
wpInsertSettingsPage -183 

NOTES 

Override this method if the dialogs for your settings pages are unusu¬ 
ally long or wide. This method is only called once for each object, 
when the settings notebook is first opened. The object then saves its 
settings notebook size in the user ini file. Therefore, if the class default 
changes, it will not affect objects that have already had their Settings 
view opened. 
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SAMPLE CODE 

The following sample is an override of wpclsQuerySettingsPageSize. 
The largest dialog in this class is 300 X 200 dialog units. 

SOM_Scope BOOL SOMLINK mclsM_wpclsQuerySettingsPageSize 

(M_MyClass*somSelf, 
PSIZEL pSizl) 

{ 

/* call the parent method to determine its size requirements */ 
parent_wpclsQuerySettingsPageSize(somSelf, pSizl); 


/* Set the height and width to the values for this class or the 
* values returned from the parent method, whichever is larger. 
*/ 

pSizl->cx = max(300, pSizl->cx); 
pSizl->cy = max(200, pSizl->cy); 


return (TRUE); 

} 


• wpdsSetSettlogsPageSize WPObJeet class 

method (Warp only) 


Sets the size of the settings notebook pages for a class. 

SYNTAX 

BOOL wpclsSetSettingsPageSize (PSIZEL pSizl ) 

PARAMETERS 

pSizl - input 

A pointer to a SIZEL structure (pg. 189) with the desired size, in dia¬ 
log units, for the settings notebook pages for this class. 

RETURNS 

TRUE—The call was successful. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called to set the default settings page size for a 
class. It is preferable to override wpclsQuerySettingsPageSize to spec¬ 
ify this value. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h and pmgpi.h 

SEE ALSO 

wpAddSettingsPages -181, wpclsOuerySettingsPageSize -185, 
wpInsertSettingsPage -183 


Settings Notebooks: Structures 


PAGEINFO (52 bytes) 

cb (ULONG) 0 

The size of the structure, in bytes, including cb itself. 

hwndPage (HWND) 4 

The window handle of the page to add if it has already been created. This can be set to 
NULLHANDLE, and a dialog resource ID can be passed in the dlgid field instead. 

pfnwp (PFNWP) 8 

The dialog procedure for the page if dlgid was specified. 

resid (ULONG) 12 

The module handle for the .DLL that contains the dialog resource if dlgid is specified. 

pCreateParams (PVOID) 16 

The creation parameters passed into WinLoadDlg when the system loads the dialog. This is 
only valid if dlgid is specified. 

dlgid (USHORT) 20 

The resource ID of the dialog to load into the page when it is first selected by the user. If this 
field is nonzero, pfnwp and resid must also be specified. 

usPageStyleFlags (USHORT) 22 

Page style flags for the notebook control: 
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Define 


Description 

BKA_STATU STEXT ON 

0x001 

Turn on status area text. This is not 
needed if SETTINGS JPAGE_NUMBERS 
is specified in usSettingsFlags. 

BKA_MAJOR 

0x040 

This page has a major tab. 

BKA_MINOR 

0x080 

This page has a minor tab. 

usPagelnsertFlags (USHORT) 


24 

Page insertion order constants for the notebook control: 

Define 


Description 

BKA_LAST 

0x02 

Insert as the last page. 

BKAJFIRST 

0x04 

Insert as the first page. 

BKA_NEXT 

0x08 

Insert as the page after ulPagelnsertld. 

BKAJPREV 

0x10 

Insert as the page before ulPagelnsertld. 

usSettimgsFlags (USHORT) 
Settings notebook flags: 


26 

Define 


Description 


SETTINGS_PAGE_NUMBERS 0x01 When this flag is set, the system will 

place page numbers on the status 
line of the notebook in the format: 
“Page n of n.” 


pszName (PSZ) 28 

The title for the tab on this page. Place a ~ in front of a letter to make it the mnemonic. Be 
careful not to duplicate mnemonics of tabs for an object’s settings notebook. 

idDefaultHelpPanel (USHORT) 32 

The extended help panel for the dialog. Workplace will create a help instance for the note¬ 
book and associate this resource ID with the dialog window. This can be 0 if no help is avail¬ 
able. 

usReserved2 (USHORT) 34 

Reserved for system use. 

pszHelpLibraryName (PSZ) 36 


The name of the help library file that contains idDefaultHelpPanel and the IDs in 
pHelpSubtable. This can be NULL if no help is available. 
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pHelpSulbtable (PUSHORT) 40 

A PHELPSUBTABLE pointer (defined in PMHELRH). This subtable will be added to the 
help table for the settings notebook. This can be 0 if there is no help available or if only 
the extended help panel will be used. The following is an example of a help subtable in 
memory: 

HELPSUBTABLE HelpSubTable []={ 2 , 

ID_DLGC0NTR0L1,IDHEL P_DLGCONTROL1, 
ID_DLGC0NTR0L2,IDHELP_DLGC0NTR0L2, 
0 , 0 } ; 

where ID_DLGCONTROLx are dialog control IDs and IDHELP_DLGCONTROLx are help 
panel IDs. 

hmo dHelp Sub table (HMODULE) 44 

This value is not used by the system. Set it to 0. 

ulPagelnsertld (ULONG) 48 

The ID of the page to place this page before or after. This value is only used if BKA_NEXT 
or BKAJPREV are specified in usPagelnsertFlags. 

Used bye wpInsertSettingsPage -183 


SIZEL 

(8 bytes) 

cx (ULONG) 

0 

Width 


cy (ULONG) 

4 

Height 



Used by: wpclsQuerySettingsPageSize -185, wpclsSetSettingsPageSize -186 




Up Menus 


W hen a user summons a pop-up menu on an object, Workplace 
creates a standard menu and then calls wpFilterPopupMenu and 
wpModifyPopupMenu on the object. These methods allow the object 
to filter out items that are unwanted and add new items. The filtered 
items are not actually removed from the menu until after both meth¬ 
ods are called. If the user presses FI while the pop-up menu is up, the 
wpMenuItemHelpSelected method is called. This is covered in the 
Help chapter (pg. 339). 
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Restrictions and Warnings 

# Not all menu items have CTXT_ constants defined for removal with 
wpFilterPopupMenu. However, each item has a WPMENXJIB_ con¬ 
stant defined in wpobject.h which can be removed with the 
MM_DELETEITEM message from a wpModifyPopupMenu override. 


instance Methods 


wpBisplayMemu (Warp) creates and displays the pop-up menu for an 
object (pg. 191). 

■wpFilterPopupMenu filters unwanted standard pop-up menu items 
(pg. 193). 

wpInsertPopupMenuItems inserts items into a pop-up menu 
(pg. 195). 

wpMenuItemSelected notifies an object when the user has selected an 
item from its pop-up menu (pg. 198). 

wpModifyPopupMenu allows the object to add items to or alter the 
pop-up menu (pg. 199). 


• wpDispSayMetiu WPObJeet instance method (Warp only) 

Creates and displays the pop-up menu for an object. 

SYNTAX 

HWND wpDisplayMenu(HWNB hwndOwner, HWNB hwndClient, 

POINTL ptlPopupPt , BLONG ulMenuType, 
BLONG ulReserved) 


PARAMETERS 

hwndOwner - input 

The window handle of the owner for this menu. This parameter is re¬ 
quired. 

hwndClient - input 

The window handle of the window on which this menu is displayed. 
This window must be owned by hwndOwner. hwndClient will be given 
the focus before the menu is displayed. If set to NBLLHANBLE, 
hwndOwner will be given the focus instead. 
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ptIPopupPt- input 

The coordinates at which to display the menu. These coordinates are 
relative to hwndClient , if specified, and hwndOwner otherwise. If 
ulMenuType is MENU_OBJECTPOPUP and hwndClient is an icon or 
tree view of a container, this parameter is ignored and the menu will be 
displayed next to the object’s icon. If ulMenuType is MENU_TITLE- 
BARPULTDOWN, this parameter is ignored and the menu is dis¬ 
played at the position of the system menu. 
ulMenuType - input 
The type of menu to display: 

Define Description 

MENU_OBJECTPOPUP 1 A pop-up for an object displayed in a 

view (that is, an icon in a folder view). 

MENU_OPENVIEWPOPUP 2 A pop-up for an open view. 

MENU JTITLEBARPULLDOWN 3 A title bar pulldown menu. 


ulReserved - reserved 
Set this parameter to zero. 

RETURNS 

(nonzero value)—The window handle of the menu. 
NULLHANDLE—An error occurred. 

HOWTO CALL 

Call this method at any time to display a pop-up menu. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpFilterPopupMenu -193, wpModifyPopupMenu -199 
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® wpFilterPopupMeiiu WPObJect instance method 

Filters out unwanted standard pop-up menu items. 

SYNTAX 

ULONG wpFilterPopupMenu(ULONG uIFlags, HWND hwndCnr, 

BOOL fMultiSelect) 

PARAMETERS 

uIFlags - input 

Multiple context menu items ORed together. This parameter contains 
the flags for desired pop-up menu items. The following is a list of pop¬ 
up menu item flags. 

Define Menu item 


CTXT_CRANOTHER 

0x001 

Create another 

CTXT_OPEN 

0x002 

Open 

CTXT_WINDOW 

0x004 

Window 

CTXT_CLOSE 

0x008 

Close 

CTXT_SETTIN GS 

0x010 

Settings 

CTXT_PRINT 

0x020 

Print 

CTXTHELP 

0x040 

Help 

CTXT_DELETE 

0x080 

Delete 

CTXT_COPY 

0x100 

Copy 

CTXT_MOVE 

0x200 

Move 

CTXT_SHAD O W 

0x400 

Create shadow 

CTXT_PROGRAM 

0x800 

Program 

CTXTJCON 

0x1000 

Icon view 

CTXT_TREE 

0x2000 

Tree view 

CTXT_DETAILS 

0x4000 

Details view 

CTXT_FIND 

0x8000 

Find 

CTXT_SELECT 

0x10000 

Select 

CTXT_ARRAN GE 

0x20000 

Arrange 
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Define Menu Item 


CTXT_SORT 

CTXT_SHUTDOWN 

CTXTJLOCKUP 

CTXTPALETTE 

CTXTREFRESH 

CTXTPICKUP 

CTXT_PUTDOWN 

CTXTJPUTDOWNCANCEL 


0x40000 

Sort 

0x80000 

Shut down 

0x100000 

Lockup 

0x200000 

Palette 

0x400000 

Refresh 

0x800000 

Pickup (Warp) 

0x1000000 

Putdown (Warp) 

0x2000000 

Cancel drag 


hwndCnr- input 

The window handle of the container of the object where the pop-up 
menu was summoned. This value is sometimes NULLHANDLE. 
fMultiSelect - input 

If set to TRUE, this pop-up menu is for multiple objects at once. 


RETURNS 

Valid context menu flags for this object ORed together. 


HOWTO CALL 

This method is generally only called by the system. 


HOWTO OVERRIDE 

Override this method to remove unwanted pop-up menu items. The 
system will pass all the CTXT_ flags in ulFlags, and it is up to the classes 
to remove items and return the result. Call the parent method first and 
store the return code; then remove any unwanted items and return the 
result. 


OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpInsertPopupMenuItems -195, wpMenuItemSelected -198, 
wpModifyPopupMenu -199, wpModifyStyle -108 
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NOTES 

Some object styles will cause WPObject to remove pop-up menu items 
in its implementation of wpFilterPopupMenu. See wpModifyStyle for 
more information on object styles. 

SAMPLE CODE 

The following samples demonstrates how to override wpFilterPopup¬ 
Menu. 

SOM_Scope ULONG SOMLINK mcls_wpFilterPopupMenu(MyClass *somSelf, 

ULONG ulFlags, 

HWND hwndCnr, 

BOOL fMultiSelect) 

{ 

ULONG ulReturn; 


/* get the parent's pop-up menu flags */ 

ulReturn = parent_wpFilterPopupMenu(somSelf,ulFlags,hwnd¬ 
Cnr, fMultiSelect) ; 

/* remove the settings menu item */ 
ulReturn &= ~CTXT_SETTINGS; 

return(ulReturn); 

} 


9 wpinsertPopupMenultems WPObject 

Instance method 


Inserts menu items into a pop-up menu. 

SYNTAX 

BOOL wpinsertPopupMenultems (HWND hwndMenu, ULONG iPosition, 

HMODULE hmod, ULONG MenuID, 
ULONG SubMenuO)) 


PARAMETERS 

hwndMenu - input 

The window handle of the pop-up menu in which to insert the items. 
iPosition - input 
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The position to place the items. This parameter has no effect in OS/2 
2.1 but works properly in Warp. 
hmod - input 

The handle for the module that contains the menu items to add. 
MenuID - input 

The ID of the menu resource that contains the new menu items to load 
and add to hwndMenu. 

SuhMenuID - input 

The ID of the submenu of hwndMenu in which the new menu items are 
to be inserted. 

Define Submenu item 


WPMENUIDJPRIMARY 

WPMENUID_OPEN 

WPMENUIDJHELP 

WPMENUIDJPRINT 

WPMENUID_SELECT 

WPMENUID_SORT 


0 Add the items to the top-level pop-up menu. 

1 Open 

2 Help 

3 Print 

4 Select 

5 Sort 


RETURNS 

TRUE—The items were successfully added. 

FALSE—An error occurred. 

HOWTO CALL 

This method should be called from an override of wpModifyPopup- 
Menu to add items to the pop-up menu. Override wpMenuItem- 
Selected for notification when the user selects one of the added items. 

There is no restriction on the value of MenuID , but the menu 
items contained in the menu represented by MenuID must be above 
WPMENUIDUSER. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h 
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SEE ALSO 

wpFilterPopupMenu -193, wpMenuItemSelected -198, 
wpModifyPopupMenu -199 

NOTES 

Be careful not to duplicate mnemonics already in use by the standard 
menu items. 

SAMPLE CODE 

The following sample demonstrates how to call wpInsertPopup- 
Menultems. 

From the .h file: 

#define ID_POPUPMENU 4000 

#define IDM_ITEMONE WPMENUID_USER 

#define IDM_ITEMTWO WPMENUID_USER+1 

From the .rc file: 

/* This entire submenu is not added to the pop-up. Only the items, 

* IDM_ITEMONE and IDM_ITEMTWO, will be added. 

*/ 

MENU ID_POPUPMENU LOADONCALL MOVEABLE DISCARDABLE 
BEGIN 

MENUITEM "-Item one", IDM_ITEMONE 
MENUITEM "I-tem two", IDM_ITEMTWO 
END 

From the .c file: 

SOM_Scope BOOL SOMLINK mcls_wpModifyPopupMenu(MyClass *somSelf, 

HWND hwndMenu, 

HWND hwndCnr, 

ULONG iPosition) 

{ 

/* call the parent method first */ 

parent_wpModifyPopupMenu(somSelf,hwndMenu,hwndCnr,iPosition); 


/* add our items to the primary menu */ 
_wpInsertPopupMenuItems(somSelf, hwndMenu, iPosition, 

hmod,ID_POPUPMENU, WPMENUID_PRIMARY); 


return(TRUE); 


} 
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® wpMenuitemSeiected WPQbject instance method 

Notifies an object when the user has selected an item from its pop-up 
menu. 

SYNTAX 

BOOL wpMenuItemSelected(HWND hwndFrame , IJLONG ulMenuId) 

PARAMETERS 

hwndFrame - input 

The frame window handle of the view containing the object. 
ulMenuId - input 

The ID of the menu item selected by the user. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when the user se¬ 
lects a pop-up menu item. 

HOWTO OVERRIDE 

Override this method to add functionality for a menu item. This 
should be done if your class added new items to the pop-up menu, or 
if you wish to replace the behavior of an existing item. All menu items 
in Warp are defined with WPMENUID_* constants in wpobject.h. If 
the item is not processed, call the parent method. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpFilterPopupMenu -193, wpInsertPopupMenuItems -195, 
wpModifyPopupMenu -199 


® wpModifyPopupMenu WPObject Instance method 

Allows the object to add items to or alter the pop-up menu. 

SYNTAX 

BOOL wpModifyPopupMenu (HWND hwncLMenu, HWNB hwndCnr, 

ULONG iPosition ) 

PARAMETERS 

hwndMenu - input 

The window handle of the pop-up menu to modify. 
humdCnr - input 

The window handle of the container of the object where the pop-up 
menu was summoned. This value is sometimes NULLHANDLE. 
iPosition - input 

The position to place the menu. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when the user sum¬ 
mons a pop-up menu. 

HOWTO OVERRIDE 

Override this method to modify the pop-up menu. Change the menu 
by calling wpInsertPopupMenuIterns and then call the parent method. 
Menu control messages can then be sent to hwndMenu to further mod¬ 
ify the menu. Items can be removed using the menu control messages 
and the WPMENUID_* constants defined in wpobject.h. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpFilterPopupMenu -193, wpInsertPopupMenuItems -195, 
wpMenuItemSelected -198 






Drag/Drop 


D irect manipulation, or drag/drop, is a feature of Presentation 
Manager. Workplace Shell makes extensive use of this interface to 
allow users to manipulate objects easily. This chapter assumes knowl¬ 
edge of the drag/drop programming interface. 
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Dragging from Workplace Shell 

Every folder in Workplace is a frame window with a container control as 
its client. 'When the container sends the frame the messages to start di¬ 
rect manipulation, Workplace starts the drag using different combina¬ 
tions of the following rendering mechanisms and rendering formats: 

“<DRM_OBJECT, DRF_OBJECT>” Specified for every object dragged 

from Workplace. 

“<DRM_OS2FILE, DRF_UNKNOWN>” Specified for nontext files (such as 

folders). 

“(DRM_OS2FILE, DRM_PRINT) X (DRF_TEXT)” Specified for printable text files. 

File objects can be dragged from Workplace to any PM application 
that supports DRM_PRINT or DRM_OS2FILE. Any window running 
on the Workplace process can accept a drop when the rendering 
mechanism is DRM_OBJECT, DRMJPRINT, or DRM OS2FILE. When 
the target has completed processing, the DM_FNDCONVERSATION 
message should be sent to pDragItem->hwndItem. If the rendering 
mechanism is DRM_OBJECT, pDragItem->ulItemID indicates the 
container record for the object dragged. The macro OBJECT_- 
FROM_PREC can be used to extract the SOM object pointer from the 
container record. 

Dragging to Workplace Shell 

If an application initiates a drag of a file and the file is dragged to 
a folder, the rendering mechanism should be DRMOS2FT T F If 
pDragItem->hstrContainerName or pDragItem->hstrSourceName is 
set, Workplace will perform the action (copy or move). If 
pDragItem->hstrContainerName is NULL, Workplace will send a 
DM_RENDERPREPARE message to the source window followed by a 
DMJRENDER message, and then the source must do the operation. 

If the file is dropped on the shredder, DRM OS2FT T F, is specified, 
and pDragItem->hstrContainerName or pDragItem->hstrSourceName 
is set, then Workplace will perform the deletion of the file. If neither 
string is set, or DRM_DISCARD is specified, then the shredder will 
send a DM_DISCARD message to the source window. 

If the file is dropped on a printer, DRM_OS2FILE is specified, and 
pDragItem->hstrContainerName or pDragItem->hstrSourceName is 
set, then Workplace will print the file. If neither string is set, or 
DRMJPRINT is used, then the printer sends a DM_PRINTOBJECT 
message to the source window. 
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Workplace Drag Methods 

Workplace provides methods to notify objects when direct manipula¬ 
tion is occurring. Many of the direct manipulation messages map 
to methods that can be overridden by any object to support 
drag/drop. 

wpDraggedOverQbject notifies an object that it is being dragged over 
another object (pg. 202). 

wpDragOver notifies an object that it is the current target in a drag 
operation (pg. 204). 

wpDrop notifies the target object that a drop has occurred 

(pg. 206). 

wpDroppedOnObject notifies an object that it has been dropped on 
another object (pg. 209). 

wpEndConversation is documented as a notification for the source ob¬ 
ject that the target sent a DM_ENDCONVERSATION message. 
Currently, this method is never called. See wpFormatDragltem for 
more information. 

wpFormatDragltem allows the source object in a drag operation to for¬ 
mat its drag information (pg. 209). 

wpRender is documented as a notification for the source object if a 
DM_RENDER message is sent by the target. Currently, this method is 
never called. See wpFormatDragltem for more information. 
wpRenderComplete is documented as a notification for the target ob¬ 
ject if a DM_RENDERCOMPLETE message is sent by the source. 
Currently, this method is never called. 


® wpDraggedOverObject \WPObject instance method 

Notifies an object that it is being dragged over another object. 

SYNTAX 

MRESULT wpDraggedOverObject(WPQbject *DraggedOverObject) 

PARAMETERS 

DraggedOverObject- input 

The target over which this object is currently being dragged. 
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RETURNS 

The return from this method is the same as the return from the 
DM_DRAGOVER message: 

Shortl: Drop indicator: 


Define 


Description 

DOR_NODROP 

0 

The object cannot be dropped at this time. The 
target may change state at some point which 
would allow the drop to occur. 

DORJDROP 

1 

The object can be dropped. Default operation 
must be set to indicate the default operation. 

DOR_NEVERDROP 

3 

The object can never be dropped. 


Short2: Default operation: 


Define 


Description 

DO_COPY 

0x10 

The copy operation. 

DO_MOVE 

0x20 

The move operation. 

DOJLINK 

0x18 

The link operation. 

DO_CREATE 

0x40 

The create operation. 

D 0_UNKN OWN 

OxBFF 

Unknown operation. 


HOWTO CALL 

This method can be called from an override of wpDragOver to allow 
the source object to decide if a drag operation is allowed. The system 
only calls this method on a file system object when it is dragged over a 
program object. 

HOWTO OVERRIDE 

Override this method to specify that a drag operation is allowed when 
the target asks for the source to decide. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpDragOver -204, wpDrop -206, wpDroppedOnObject -209 
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@ wpDragOver WPObject instance method 


Notifies an object that it is the current target in a drag operation. 

SYNTAX 

MRESULT wpDragOver (HWND hwndCnr\ PDRAGINFO pdrglnfo) 

PARAMETERS 

hnwdCnr - input 

The handle to the target container in the drag operation. 
pdrglnfo - input 

A pointer to the DRAGINFO structure (pg. 211) passed from the 
DM_DRAGOVER message. 

RETURNS 

The return from this method is the same as the return from the 
DM_DRAGOVER message: 

Shortl: Drop indicator: 


Define 


Description 

DOR_NODROP 

0 

The object cannot be dropped at this time. The 
target may change state at some point when the 
drop is allowed. 

DORJDROP 

1 

The object can be dropped. Default operation 
must be set to indicate the default operation. 

DOR_NODROPOP 

2 

The object cannot be dropped at this time 
because the current operation is not acceptable. 

DORJNEVERDROP 

3 

The object can never be dropped. 


Short2: Default operation: 


Define 


Description 

DO_COPY 

0x10 

The copy operation. 

DO_MOVE 

0x20 

The move operation. 

DOJLINK 

0x18 

The link operation. 

DO_CREATE 

0x40 

The create operation. 

D G_UNKN OWN 

OxBFF 

Unknown operation. 
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HOWTO CALL 

This method is generally called by the system when the container re¬ 
ceives the DM_DRAGOVER message. wpDragOver is called on the cur¬ 
rent target object for the drag operation. 

HOWTO OVERRIDE 

Override this method to specify whether this drag operation is al¬ 
lowed. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpDraggedOverObject -202, wpDrop -206, wpDroppedOnObject -209 

SAMPLE CODE 

The following sample demonstrates how to override wpDragOver. In 
this example, only WPDataFile descendants will be allowed to be 
dropped on objects of this class. 

SOM_Scope MRESULT SOMLINK mcls_wpDragOver(MyClass *somSelf, 

HWND hwndCnr, 

PDRAGINFO pdrglnfo) 


PDRAGITEM pDragltem; 

ULONG ulCount; 

USHORT usDrop = DOR_DROP, usDefaultOp = DO_MOVE; 

SOMAny *Object; 

/* Loop through the drag item structures to see what is being 
* dragged over this object. 

*/ 

for (ulCount=0; usDrop == DOR_DROP && ulCount < pdrglnfo->cditem; 
ulCount++) 

{ 

pDragltem = DrgQueryDragitemPtr(pdrglnfo, ulCount); 

/* 

* For each drag item, verify it is a WPS object 

* "<DRM_OBJECT,DRF_OBJECT>". If it is, only allow data files to 

* be dropped. 

*/ 

if (DrgVerifyRMF (pDragltem, "DRM_OBJECT" , "DRF__OBJECT" ) ) 
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/* pDragItem->ulItemID is the RECORDCORE structure for the 

* object. OBJECT_FROM_PREC is a macro defined in wpobject.h 

* that will give the pointer of a Workplace object given its 

* container record. 

*/ 

Object = OBJECT_FROM_PREC(pDragItem->ulItemID); 

/* If it is not a data file, do not allow the drop, (wpdataf.h 

* must be included to use the _WPDataFile variable) 

*/ 

if (!_somIsA(Object, _WPDataFile) ) 
usDrop = DOR_NEVERDROP; 


else 

usDrop = DOR_NEVERDROP; 

} 

return MRFROM2SHORT(usDrop, usDefaultOp); 


® wpDrop WPObjeet instance method 


Notifies the target object that a drop has occurred. 

SYNTAX 

MRESULT wpDrop (HWND hwndCnr , PBRAGINFO pdrglnfo, 
PBRAGITEM pdrgltem) 


PARAMETERS 

hnwdCnr - input 

The handle to the target container in the drag operation. 
pdrglnfo - input 

The pointer to the DRAGINFO structure (pg. 211) passed from the 
DM_DROP message. 
pdrgltem - input 

A pointer to a DRAGITEM structure (pg. 212). On the first call of 
wpDrop, pdrgltem points to the first DRAGITEM of pdrglnfo. If 
RC_DROP_ITEMCOMPLETE is returned, wpDrop will be called for 
each item of pdrglnfo , and pdrgltem will point to its corresponding 
DRAGITEM. See the sample code below. 



Drag/Drop 


207 


RETURNS 


Define 


Description 


RG_DROP_ITEMCOMPLETE 1 Only the item specified by pdrgltem has 

been processed. wpDrop should be 
called again for each item. 

RC_DROP_DROPCOMPLETE 2 The entire drop has been successfully 

processed. 

RC_DROP_RENDERING 0 The target cannot render the object and 

source rendering is requested. 
Workplace will send required messages 
to the source. 


RC DROP ERROR 


-1 An error has occurred. 


HOWTO CALL 

This method is generally called only by the system on the current tar¬ 
get object when the container receives the DM_DROP message. 

HOWTO OVERRIDE 

Override this method to process a drop on this object. Override 
wpDragOver to prevent unwanted items from being dropped. The 
WPFolder class will process this override by performing copy, move, 
create shadow, or create from template operations depending on the 
value of pdrgItem->usOperation. When files are dropped on 
WPProgram objects, they process wpDrop by running the program 
specified in its P ROOD If PAILS and passing the file as a parameter. The 
WPShredder class will delete objects or files from the wpDrop over¬ 
ride. Call the parent method only if you wish to let the parent perform 
these functions. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpDraggedOverObject -202, wpDragOver -204, wpDroppedOnObject 
-209 
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SAMPLE CODE 

The following sample demonstrates how to override wpDrop. This 
override is from the same class as the wpDragOver sample. Only ob¬ 
jects descendant from WPDataFile were allowed to be dropped on ob¬ 
jects of this class. Since wpDragOver filtered out unwanted drag oper¬ 
ations, it is guaranteed that at the point when the wpDrop method is 
called, all the items are data file objects. 

SOM_Scope MRESULT SOMLINK mcls_wpDrop(MyClass *somSelf / 

HWND hwndCnr, 

PDRAGINFO pdrglnfo, 

PDRAGITEM pdrgltem) 

{ 

SOMAny ^Object; 


/* Process this drop one item at a time using the pdrgltem 

* pointer. If we wanted to, we could have looped through the drag 

* items from the pdrglnfo structure and processed all the items 

* in this call. 

*/ 


/* ulItemID is the container record for the object. 

* OBJECT_FROM_PREC returns the object pointer given the record 

* pointer. 

*/ 

Object = OBJECT_FROM_PREC(pdrgltem->ulItemID); 

/* Perform an action on this object. In this example we'll do 

* something simple and set the readonly attribute on the object. 
*/ 

_wpSetAttr(Object, _wpQueryAttr(Object) I FILE_READONLY); 

/* Return RC_DROP_ITEMCOMPLETE so wpDrop will be called once for 

* every item in this drag operation. 

*/ 

return (MRESULT) RC_DROP_ITEMCOMPLETE; 


} 



Drag/Drop 


209 


® wpDroppedOnObject WPObJect instance method 

Notifies an object that it has been dropped on another object. 

SYNTAX 

MRESULT wpDroppedOnObject (WPObject *DroppedOnObject) 

PARAMETERS 

DroppedOnObject - input 

The target on which this object has just been dropped. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called during the override of wpDrop to allow the 
source object to process the drop operation. Call this method only 
when wpDraggedOverObject is also called on the source object to de¬ 
cide if a drag operation is allowed (this is done from the wpDragOver 
override). The system only calls this method on a file system object 
when it is dropped on a program object. 

HOWTO OVERRIDE 

Override this method to process a drop operation when the target re¬ 
quests it. This is analogous to source rendering. 

OTHER INFO 

Include file: wpobject.h 

SEE ALSO 

wpDraggedOverObject -202, wpDragOver -204, wpDrop -206 


® wpFormatDragltem WPObJect instance method 


Allows the source object in a drag operation to format its drag infor¬ 
mation. 
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SYNTAX 

BOOL wpFormatDragltem (PDRAGITEM pdrgltem ) 

PARAMETERS 

pdrgltem - input 

A pointer to the DRAGITEM (pg. 212) structure that represents this 
object. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system to notify the object 
to initialize its DRAGITEM structure. 

HOWTO OVERRIDE 

Override this method to change the DRAGITEM structure. You can 
call the parent method first to allow the parent classes and WPObject 
to first set up pdrgltem and then make the desired changes. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpDraggedOverObject -202, wpDragOver -204, wpDrop -206, 
wpDroppedOnObject -209 

NOTES 

If source rendering is desired, override wpFormatDragltem. Change 
the rendering mechanism, if desired, and free the hstrSourceName in 
the DRAGITEM structure. 

Currently, the methods wpEndConversation and wpRender do 
not function as they are documented. When the target sends the 
DM_RENDERPREPARE, DM RENDER, and DM ENDCONVERSA- 
TION messages, they are sent to the window handle stored in 
pdrgltem->hwndltem. This window does not process the messages to 
call the notification methods. To work around this problem, create an 
invisible window to process these messages and change the 
pdrgltem>hwndltem to point to that window. 
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cbBraginf© (ULONG) 

The size of this structure plus all the drag items. 

cbBragitem (USHORT) 

The size of DRAGITEM. 

usOperatiom (USHORT) 

The current drag operation: 


Define 


Description 

DO_COPY 

0x10 

The copy operation. 

DO_MOVE 

0x20 

The move operation. 

DO_LINK 

0x18 

The link operation. 

DO_CREATE 

0x40 

The create operation. 

DO_UNKNOWN 

OxBFF 

Unknown operation. 


hwiidSouree (HWND) 

The handle of the source window. 

xBrop (SHORT) 

The x coordinate for the drop position. 

yDrop (SHORT) 

The y coordinate for the drop position. 

cditem (USHORT) 

The number of drag items. 

usReserved (USHORT) 

Reserved value. 

Used by: wpBragOver -204, wpDrop -206 
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hwndltem (HWND) 0 

The window to communicate with for this item. 

ulItemlD (ULONG) 4 

The ID of the item dragged. For Workplace objects, this is a pointer to the container record 
for the object. OBJECT_FROM_PREC can be used to obtain an object pointer from a con¬ 
tainer record. 

hstrType (HSTR) 8 

The type of the item. 

hstrRMF (HSTR) 12 

The rendering mechanism and format. 

hstrContainerName (HSTR) 16 

The name of the source container. 

hstrSourceName (HSTR) 20 

The name of the item at the source. 

hstrTargetName (HSTR) 24 

The suggested name for the item at the target. 

exOffset (SHORT) 28 

The x offset of the image from the hotspot of the mouse pointer. 

cyOffset (SHORT) 30 

The y offset of the image from the hotspot of the mouse pointer. 

fsContro! (USHORT) 32 

The source object control flags. 

fsSupportedOps (USHORT) 34 

The operations supported by the source. 

Define Description 


DO_ 

.COPYABLE 

0x01 

The item can be copied. 

DO_ 

_MOVEABLE 

0x02 

The item can be moved. 

DO_ 

.LINKABLE 

0x04 

The item can be linked. 

DO 

CREATEABLE 

0x08 

The item can be created. 


Used by: wpDrop -206, wpFormatDragltem -209 




F ile system objects are all descendants from the base class 
WPFileSystem. Directories are descended from WPFolder, and 
files fromWPDataFile. One advantage of defining a subclass of 
WPFileSystem is that its instances can be moved onto a diskette or 
across a LAN. This is because the object’s class data is stored in the 
Extended Attributes (EAs) of the file or directory it represents. 
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Data Files 

When a WPDataFile descendant saves its instance data, the class name 
of the object is written to the EAs. The class of a data file object is always 
determined by the class name specified in the .CLASSINFO EA, if pre¬ 
sent. Note that all file system classes can override wpclsQueryln- 
stanceType and/or wpclsOuerylnstanceFilter to specify lists of types or 
extensions of its instances. Workplace builds a list containing classes 
and their corresponding .TYPE and extension lists by calling wpcls- 
OuerylnstanceType and wpclsQuerylnstanceFilter on each file system 
subclass. When a data file without a .CLASSINFO EA is awakened, the 
.TYPE and extension is checked against this list of classes. If no match¬ 
ing classes are found, the WPDataFile class is used. 

Restrictions and Warnings 

® The format of the .CLASSINFO EA is private and should not be ma¬ 
nipulated directly. Only public methods can be used to change in¬ 
stance data defined by file system classes. 
m File system objects are designed to have their file names correspond 
to their titles as much as possible. Therefore, when you call 
wpSetTitle, the file name is also changed. 


instance Methods 


wpQueryAttr returns the file attributes of an object (pg. 215). 
wpQueryCreation returns the creation date and time of an object 

( pg. 2 16) . 

wpQueryEASize returns the size of the extended attributes of an ob- 
ject (pg. 217). 

wpQueryFileName (Warp) returns the physical file name of an object. 
wpQueryRealName provides the same functionality, but checks the 
size of the buffer. Therefore, wpQueryRealName should be used in¬ 
stead. 

wpQueryFileSize returns the size of the file represented by an object 

(pg. 218). 
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wpQiieryLastAccess returns the last access date and time of an object 
(pg- 219). 

wpQneryLastWrite returns the last write date and time of an object 
(pg. 219). 

wpQneryRealName returns the physical file name of an object 

(pg. 220). 

wpQueryType returns the value of the .TYPE EA of an object 
(pg. 221). 

wpRefresh refreshes the file system information of an object 
(pg. 222). 

wpSetAttr sets the file attributes of an object (pg. 223). 
wpSetRealName is documented as setting the physical file name of an 
object. However, this method only sets the WPFileSystem internal in¬ 
stance data to a new name and does not affect the underlying file 
name. It is, therefore, not useful. 
wpSetType sets the .TYPE EA of an object (pg. 224). 
wpVerifyUpdateAccess (Warp) verifies write access to a file system ob¬ 
ject (pg. 225). 


# wpQueryAttr WPFileSystem instance method 

Returns the file attributes of an object. 

SYNTAX 

ULONG wpQueryAttr ( ) 

PARAMETERS 

none 

RETURNS 

The attribute flags of the file. Any combination of the following may be 
returned: 
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Define 


Description 

FILE_NORMAL 

0x000 

The file can be read from or written to. No 
attributes are specified. 

FILE_READONLY 

0x001 

The file can be read from but not written to 

or deleted. 

FILE_HIDDEN 

0x002 

The file is hidden and does not show up in 
normal directory listings. Hidden file 
objects are usually invisible in folders unless 
the Include page of the folder specifies 
otherwise. 

FILE_SY5TEM 

0x004 

The file is a system file. 

FILEJDIRECTORY 

0x010 

The file is a subdirectory. 

FILE_ARCHIVED 

0x020 

The file has been archived. 


HOWTO CALL 

This method can be called at any time to determine the attributes of 
the file represented by a file system object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h and bsedos.h define: 

INCLJ30SFILEMGR 


SEE ALSO 

wpSetAttr-223 


• wpQueryCreation WPFiSeSystem instance method 


Returns the creation date and time of an object. 

SYNTAX 

ULONG wpOueryCreation(FDATE *fdate, FTIME *ftime) 
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PARAMETERS 

fdate - input/ output 

A pointer to an FDATE structure (pg. 228) which, upon return, will be 
filled with the creation date of the file represented by this object. 
ftime - input/output 

A pointer to an FTIME structure (pg. 228) which, upon return, will be 
filled with the creation time of the file represented by this object. 

RETURNS 

Reserved 

HOWTO CALL 

This method can be called at any time on any file system object. Note 
that the creation date and time is not supported by the FAT file system. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h and bsedos.h define: 

IN CL_D O SFILEMGR 


SEE ALSO 

wpQueryLastAccess-219, wpQuery LastWrite-219 


• wpQueryEASize WPFiSeSystem Instance method 

Returns the size of the extended attributes of an object. 

SYNTAX 

ULONG wpQueryEASize ( ) 

PARAMETERS 

none 

RETURNS 

The size, in bytes, of the extended attributes for the file represented by 
this object. 
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HOWTO CALL 

This method can be called at any time on any file system object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpQueryFileSize -218 


• wpQueryFileSize WPFiieSystem Instance method 

Returns the size of the file represented by an object. 

SYNTAX 

ULONG wpQueryFileSize ( ) 

PARAMETERS 

none 

RETURNS 

The size of the file, in bytes, represented by this object. 

HOWTO CALL 

This method can be called at any time on any file system object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpQueryEASize -217 
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# wpQueryLastAccess WPFileSystem instance method 


Returns the last access date and time of an object. 

SYNTAX 

ULONG wpQueryLastAccess (FDATE *fdate, FTIME Ttime) 

PARAMETERS 

fdate - input/output 

A pointer to an FDATE structure (pg. 228) which, upon return, will be 
filled with the last access date of the file represented by this object. 
ftime - input/output 

A pointer to an FTIME structure (pg. 228) which, upon return, will be 
filled with the last access time of the file represented by this object. 

RETURNS 

Reserved 

HOWTO CALL 

This method can be called at any time on any file system object. Note 
that the last access date and time is not supported by the FAT file system. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h and bsedos.h define: 

INCLJDOSFILEMGR 


SEE ALSO 

wpQueryCreation -216, wpQueryLastWrite -219 


® wpQueryLastWrite WPFileSystem instance method 


Returns the last write date and time of an object. 

SYNTAX 

ULONG wpQueryLastWrite (FDATE * fdate, FTIME * ftime) 
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PARAMETERS 

fdate - input/output 

A pointer to an FDATE structure (pg. 228) which, upon return, will be 
filled with the last write date of the file represented by this object. 
ftime - input/output 

A pointer to an FTIME structure (pg. 228) which, upon return, will be 
filled with the last write time of the file represented by this object. 

RETURNS 

Reserved 

HOWTO CALL 

This method can be called at any time on any file system object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h and bsedos.h define: 

INCLJDOSFILEMGR 


SEE ALSO 

wpQueryCreation -216, wpQueryLastAccess -219 


• wpQueryReaSName WPFIleSystem instance method 

Returns the physical file name of an object. 

SYNTAX 

BOOL wpQueryRealName(PSZ pszFileName, PULONG pcb, BOOL 

bQualified) 


PARAMETERS 

pszFileName - input/output 

A pointer to the string buffer in which to return the real file name of 
the object. If set to NULL, the required size is returned in pcb . 
pcb - input/output 

The size of the pszFileName buffer. If pszFileName is set to NULL, the re¬ 
quired size is returned. 
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bOualified - input 

TRUE—Return the fully qualified path for the object. 

FALSE—Only return the name of the file and not the full path. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any file system object. The 
physical file name and the title of a file system object are usually simi¬ 
lar; however, the physical file name is modified to conform to any nam¬ 
ing rules of the file system. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpOueryTitle -118 


• wpQueryType WPFiSeSystem instance method 


Returns the value of the .TYPE EA of an object. 

SYNTAX 

PSZ wpQueryType ( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the string containing all the types in the .TYPE EA of 
the object. Multiple types are separated by the line feed character: 4 \n’. 

HOWTO CALL 

This method can be called at any time on a file system object. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpSetType -224 


© wpRefresh WPFIIeSystem instance method 

Refreshes the file system information of an object. 

SYNTAX 

BOOL wpRefresh (ULONG ulView YVOIDpReserved) 

PARAMETERS 

ulView - input 

If refreshing a folder view, set ulView to either OPEN_CONTENTS, 
OPEN_TREE, or OPEN_DETAILS. Otherwise, set it to zero. 
pReserved - reserved 
Set this value to zero. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any file system object to re¬ 
fresh its file system information. The WPFolder override of this 
method will refresh any open views to display the current contents of a 
folder. Workplace is notified by the file system when a file changes and 
updates the object by calling this method from a background thread. 
This method should be used to force an object to immediately reflect 
file system changes. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpfsys.h 


© wpSetAttr WPFIIeSystem instance method 

Sets the file attributes of an object. 

SYNTAX 

BOOL wpSetAttr (ULONG attrFile) 

PARAMETERS 

attrFile - input 

The new file attributes for the object. OR together any combination of 
attribute flags. 


Define 


Description 

FILE_N ORMAL 

0x000 

The file can be read from or written to. No 
attributes are specified. 

FILEJREADONLY 

0x001 

The file can be read from but not written to 

or deleted. 

FILE_HIDDEN 

0x002 

The file is hidden and does not show up in 
normal directory listings. Hidden file 
objects are usually invisible in folders unless 
the Include page specifies otherwise. 

FILE_SYSTEM 

0x004 

The file is a system file. 

FXLE_DIRECTORY 

0x010 

The file is a subdirectory. 

FILE_ARCHIVED 

0x020 

The file has been archived. 


RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to set the attributes of the file 
represented by a file system object. wpQueryAttr should be called first 
to determine the current attribute flags. Then make the desired mod¬ 
ifications on the return code and pass it to wpSetAttr. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h and bsedos.h define: 

INCLDOSFILEMGR 


SEE ALSO 

wpOueryAttr -215 

SAMPLE CODE 

The following sample demonstrates how to call wpSetAttr. Object is a 
SOMAny pointer that has already been set to point to a file system object. 

/* Make this object read only. */ 

_wpSetAttr(Object, _wpQueryAttr(Object) I FILE_READONLY); 


• wpSetType WPFileSystem instance method 

% 

Sets the value of the .TYPE EA of an object. 

SYNTAX 

BOOL wpSetType (PSZpszTypes, PFEA2LIST pfeat) 

PARAMETERS 

pszTypes - input 

The pointer to the string containing the new value for the .TYPE EA of 
the object. Multiple types are separated by the line feed character: ‘\n\ 
pfeal - reserved 
Set this to zero. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any file system object to set 
its .TYPE EA. Be aware that all of the types are stored in the same 
string, so when wpSetType is called, the pszTypes list replaces the pre¬ 
vious list for the object. Call wpOueryType to determine the current 
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list of types. Discard the unwanted ones from the return code and add 
new ones if desired and pass the new string to wpSetType. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpOueryType -221 


® ¥/p Verify Update Access WPFISeSystem 

Instance method (Warp only) 


Verifies write access to a file system object. 

SYNTAX 

ULONG wpVerifyUpdateAccess( ) 

PARAMETERS 

none 

RETURNS 

NO_ERROR—Write access to this object is successful. 

Otherwise—The error returned from DosOpen. 

HOWTO CALL 

This method can be called at any time on any file system object to ver¬ 
ify that it can be updated. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 
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Class Methods 


wpclsQuerylnstanceType returns the list of types for data files of this 
class (pg. 226) 

wpclsQuerylnstanceFilter returns the list of extensions for data files of 
this class (pg. 227) 


• wpclsQuerylnstanceType WPFileSystem class method 

Returns the list of types for data files of this class. 

SYNTAX 

PSZ wpclsQuerylnstanceType ( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the string containing the names of the file types sup¬ 
ported by this class. Multiple types are separated by commas. 

HOWTO CALL 

This method is only called by the system when a class is loaded. 

HOWTO OVERRIDE 

Override this method to specify the types of data files that should use 
this class. Workplace will store this list and, whenever a data file is awak¬ 
ened, if the type of the file matches one in the list for this class, the 
data file will be awakened as an instance of this class. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpclsQuerylnstanceFilter -227, wpQueryType -221, wpSetType -224 
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# wpclsQueryfnstanceFiSter WPFileSystem class method 

Returns the list of extensions for data files of this class. 

SYNTAX 

PSZ wpclsQueryInstanceFilter( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the string containing the names of the file extensions 
supported by this class. Multiple extensions are separated by commas 

(“*.TXT*.DOC”). 

HOWTO CALL 

This method is only called by the system when a class is loaded. 

HOWTO OVERRIDE 

Override this method to specify the extensions of data files that should 
use this class. Workplace will store this list and, whenever a data file is 
awakened, if the extension of the file matches a filter in the list for this 
class, the data file will be awakened as an instance of this class. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpclsQuerylnstanceType -226 
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File System Objects: Structures 




(2 bytes) 


§p 0 


day (UINT) 

(5 bits) 

The day of the year. 


month (UINT) 

(4 bits) 

The numeric representation for the month. 


year (UINT) 

(7 bits) 

The number of years since 1980. 



Used by: wpQueryCreation -216, wpQueryLastAccess -219, wpQueryLastWrite -219 


FT! HE 

A. . * Tv 

TV *4* i 



(2 bytes) 

twosecs (UINT) 

The number of two-second increments. 




(5 bits) 

minutes (UINT) 

The number of minutes. 




(6 bits) 

hours (UINT) 

The number of hours. 




(5 bits) 


Used by: wpQueryCreation -216, wpQueryLastAccess -219, wpQueryLastWrite -219 





Folder Objects 


O bjects that represent file system directories are descendants of the 
WPFolder class. Folders are used to contain other objects. Folders 
automatically contain any file that is in the directory represented by 
the folder, but can also contain abstract or transient objects. This 
means that not all folder contents can be viewed from the file system. 
Some are stored in the OS2.INI file (abstracts) and some exist only in 
memory (transients). When the contents of a folder are loaded into 
memory, it is called populating the folder. This can be accomplished 
directly by calling the wpPopulate method. The contents of a folder 
can be enumerated with the wpOueryContent method. The content 
list of a folder contains only the objects that are currently awake. Be 
sure to populate a folder before querying its content list. 

Workplace is designed such that all objects must be created in a 
folder. Once an object has been created, its container record can be in¬ 
serted into any container using the wpCnrlnsertObject method. 
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Restrictions and Warnings 

# The container view functionality of a folder is tightly integrated with 
the WPFolder class. It is therefore impossible to create a class that is 
not descendant from WPFolder that can contain other objects. 
Folder objects must be real file system directories. 


instance Methods 


wpAddFirstChild (Warp) awakens the first subfolder of a folder 
(pg. 231). 

wpAddToContent (Warp) adds an object to a folder’s content list 
(pg. 232). 

wpCnrlnsertObject inserts an object into the specified container 
(pg. 233). 

wpCnrRemoveObject removes an object from the specified container 
(pg. 234). 

wpContainsFolders returns whether a folder contains subfolders 
(pg- 235). 

wpBeleteContents deletes the contents of a folder (pg. 236). 
wpBeleteFromContent (Warp) removes an object from a folder’s con¬ 
tent list (pg. 237). 

wpIsCurrentBesktop returns whether a desktop object is the current 
desktop (pg. 238). 

wpIsBetailsColnmnYisible (Warp) returns whether a details data col¬ 
umn is visible (pg. 239). 

wpIsSortAttribAvailable (Warp) returns whether a sort attribute is 
available (pg. 240). 

wpModifyFldrFlags (Warp) sets the flags describing the current state of 
a folder (pg. 241). 

wpPopulate awakens the contents of a folder (pg. 242). 
wpQueryContent enumerates the contents of a folder (pg. 243). 
wpOneryFldrAttr returns the attributes of a folder’s view 
(pg. 245). 

wpQueryFldrBetailsClass returns the class used to define the columns 
of the details view of a folder (pg. 247). 

wpQueryFldrFlags returns the flags describing the current state of a 
folder (pg. 248). 
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wpQueryfldrFont returns the font used for the text in a folder view 
(pg. 248). 

wpQueryFldrSortClass (Warp) returns the sort class for a folder 
(pg. 250). 

wpQueryFolder (Warp) returns the folder that contains an object 
(pg. 251). 

wpQueryNextlconPos returns the next icon position for an object be¬ 
ing inserted into the icon view of a folder (pg. 251). 
wpSetDetailsColumiiyisibility (Warp) hides or unhides a details data 
column (pg. 252). 

wpSetFldrAttr sets the attributes of a folder’s view (pg. 253). 
wpSetFldrDetailsClass sets the class used to define the columns of the 
details view of a folder (pg. 254). 

wpSetFldrFlags sets the flags describing the current state of a folder 
(pg. 255). 

wpSetFldrFont sets the font used for icon text in a folder view 
(pg. 256). 

wpSetFldrSortClass (Warp) sets the sort class for a folder (pg. 257). 
wpSetNextlconJPos sets the next icon position for an object being in¬ 
serted into a folder. Currently, this method has no effect. 
wpSetSortAttribAvailable (Warp) adds or removes a sort attribute for a 
folder’s Sort pulldown in the pop-up menu (pg. 258). 


• wpAddFIrstChiSd WPFolder instance method 

(Warp only) 


Awakens the first subfolder of a folder. 

SYNTAX 

WPObject * wpAddFirstChild( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—The object pointer of a child folder of the folder. 
NULL—An error occurred. 
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HOWTO CALL 

This method can be called at any time to awaken one child folder in a 
folder. The system calls this method on each visible folder in a tree 
view to show the proper expansion emphasis. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpPopulate -242 


@ wpAddToContent WPFoIder instance method 

(Warp only) 


Adds an object to a folder’s content list. 

SYNTAX 

BOOL wpAddToContent (WPObject * Object) 

PARAMETERS 

Object - input 

The pointer to the object to add. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is called only by the system to notify a folder that an ob¬ 
ject must be added to its content list in memory. 

HOWTO OVERRIDE 

Override this method for notification when an object is added. This is 
useful for subclasses that define their own views. You must call the par¬ 
ent method. 
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OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpDeleteFromContent -237, wpPopulate -242, wpQueryContent -243 


# wpCnrlnsertObject WPObfect Instance method 

Inserts an object into the specified container. 

SYNTAX 

BOOL wpCnrlnsertObject(HWND hwndCnr, PPOINTL pptllcon, 

PMINIRECORDCORE preccParent, PRE- 
CORDINSERT pRecInsert ) 

PARAMETERS 

hwndCnr - input 

The window handle of the container control in which to insert the ob¬ 
ject. The container must be created from a thread running on the 
Workplace Shell process. 
pptllcon - input 

A pointer to a POINTL structure (pg. 137) which contains the icon 
postion at which to insert the object. This pointer must be set, but the 
POINTL structure can contain zeros if the view for this container does 
not support icon positions or the next available position should be 
used. 

preccParent - input 

A pointer to the parent record for this object. If hwndCnr is not a tree 
view or this record does not have a parent, set this to NULL. 
pRecInsert - input 

A pointer to a RECORDINSERT structure (pg. 267) which can be 
passed to specify more information about how this object is to be in¬ 
serted into the container. This parameter can be set to NULL . 

RETURNS 

TRUE—The object was successfully inserted into the container. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to insert an object into a con- 
tainer. Workplace will subclass the container and add context menu 
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and drag/drop support. These records must be removed with 
wpCnrRemoveObject or wpclsRemoveObjects when they are no 
longer needed. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h and pmstddlg.h define: 

INCL_WINSTD CNR 


SEE ALSO 

wpclsInsertMultipleObjects -264, wpclsRemoveObjects -265, 
wpCnrRemoveObject -234 

NOTES 

To manipulate objects that have been added to a container with 
wpCnrlnsertObject, use the normal CM_* messages for containers to 
obtain pointers to the MINIRECORDCORE structures. Workplace de¬ 
fines two useful macros in wpobject.h. Pass a container record for an 
object to OBJECT_FROM_PREC and it will return the object pointer. 
Pass a container record to USERWORD_FROM_PREC and it will re¬ 
turn a pointer to a user-defmeable ULONG for that record. 

Objects must first be created in a folder and then can be inserted 
into other containers using wpCnrlnsertObject. The Nowhere folder 
<WP_NOWHERE> can be used as a place to create objects when it 
does not make sense for them to exist in a folder. 


® wpCnrRemoveObject WPObject instance method 


Removes an object from the specified container. 

SYNTAX 

BOOL wpCnrRemoveObject (HWND hwndCnr) 

PARAMETERS 

hwndCnr - input 

The window handle of the container control from which to remove the 
object. 
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RETURNS 

TRUE—The object was successfully removed from the container. 
FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to remove an object from a con¬ 
tainer. This method can only be called on objects that have been inserted 
into hwndCnrmth wpCnrlnsertObject or wpclsInsertMultipleObjects. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO: 

Include files: wpobject.h 

SEE ALSO: 

wpclsInsertMultipleObjects - 264, wpclsRemoveObjects - 265, 
wpCnrlnsertObject - 233 


# wpGontafnsFolders WPFolder instance method 


Returns whether a folder contains subfolders. 

SYNTAX 

BOOL wpContainsFolders(BOOL *pfSubFolders) 

PARAMETERS 

pfSubFolders - input/output 

A pointer to a BOOL which, upon return, will be set to TRUE if the 
folder contains subfolders and FALSE if it does not. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any folder object to determine 
if it contains subfolders. The folder does not have to be populated. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO: 

Include files: wpfolder.h 

SEE ALSO 

wpPopulate -242 


® wpDeleteContents WPFolder Instance method 

Deletes the contents of a folder. 

SYNTAX 

BOOL wpDeleteContents (ULONG /Confirmations) 

PARAMETERS 

f 'Confirmations - input 

OR together desired delete confirmation flags. If CONFIRM_DELETE 
is specified, the user will be prompted for each object deleted. If CON- 
FIRM_DELETEFOLDER is specified, the user will be prompted if this 
object contains a folder. Call wpQueryConfirmations on any object to 
obtain the user confirmation preferences. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any folder object to delete its 
contents. wpDeleteContents will first call wpPopulate, and then call 
wpDelete on each object contained in the folder using the specified 
confirmation flags. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 
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SEE ALSO 

wpConfirmDelete -40, wpDelete -51, wpPopulate -242, 
wpOueryConfirmations -111 

NOTES 

wpDelete calls wpDeleteContents if the object being deleted is a 
folder; wpDeleteContents in turn calls wpDelete on each object in the 
folder. Therefore, wpDeleteContents will be called recursively for each 
subfolder in this folder tree. 

RESTRICTIONS/WARNINGS: 

® When calling this method on a folder that contains many objects, 
create a separate thread to make the call. This will avoid hanging the 
system while the deletions take place. 

® wpDeleteContents calls wpPopulate first and then deletes the con¬ 
tents of the folder. Therefore, do not invoke this method on the self 
pointer passed to a wpPopulate override. 


# wpDeSeteFromContent WPFolder instance method 

(Warp only) 


Removes an object from a folder’s content list. 

SYNTAX 

BOOL wpDeleteFromContent (WPObject * Object) 

PARAMETERS 

Object - input 

The pointer to the object to be removed. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is called only by the system to notify a folder that an ob¬ 
ject must be removed from its content list in memory. 
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HOWTO OVERRIDE 

Override this method for notification when an object is removed. This 
is useful for subclasses that define their own views. You must call the 
parent method. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpAddToContent -232, wpPopulate -242, wpQueryContent -243 


9 wpIsCurrentDesktop WPOesktop instance method 


Returns whether a desktop object is the current desktop. 

SYNTAX 

BOOL wpIsCurrentDesktop ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—This object is the current desktop. 

FALSE—This object is not the current desktop or an error occurred. 

HOWTO CALL 

This method can be called at any time on any desktop object to query 
if it is the currently active desktop. The active desktop is the one that 
opens when Workplace is loaded. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdesk.h 

SEE ALSO 

wpclsQueryActiveDesktop -259, wpclsQueryActiveDesktopHWND -260, 
wpclsQueryObjectFromPath -76 
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NOTES 

It is possible for users to have multiple desktops on their machines but 
only one may be active at a time. If you have a pointer for a 
WPDesktop object, you can find out if it is the active desktop by call¬ 
ing wpIsCurrentDesktop. Note that since this is a WPDesktop 
method, it cannot be called on all folder instance pointers. It must be 
called on an instance pointer of WPDesktop or a subclass of 
WPDesktop. Another way to obtain the object pointer for the current 
desktop is to call wpclsQueryObiectFromPath passing “<WP_DESK- 
TOP>” as the path. 


# wpIsDetailsColumnYisible WPFolder instance method 

(Warp onSy) 


Returns whether a details data column is visible. 

SYNTAX 

BOOL wpIsDetailsColumnVisible (ULONG index) 

PARAMETERS 

index - input 

The index of the details data column. 

RETURNS 

TRUE—The column is visible. 

FALSE—The column is hidden. 

HOWTO CALL 

Call the method at any time to determine if a column in a folder’s de¬ 
tails view is visible. The folder’s details view columns are determined by 
the folder’s details class. This class can be queried with 
wpQueryFldrDetailsClass. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 
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SEE ALSO 

wpclsQueryDetailsInfo -123, wpQueryFldrDetailsClass -247, 
wpSetDetailsColumnVisibility -252 


• wpisSortAttribAvailable WPFolder instance method 

(Warp only) 

Returns whether a sort attribute is available. 

SYNTAX 

BOOL wpIsSortAttribAvailable (ULONG index ) 

PARAMETERS 

index - input 

The index of the details data column. 

RETURNS 

TRUE—The attribute is displayed in the Sort pulldown of the folder’s 
pop-up menu. 

FALSE—The attribute is not available. 

HOWTO CALL 

Call this method at any time to determine which sort attributes are 
available to the user in the pop-up menu of a folder. These sort attrib¬ 
utes are those defined by the folder sort class. This class can be queried 
with wpQueryFldrSortClass. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpclsQueryDetailsInfo -123, wpIsDetailsColumnVisible -239, 
wpQueryFldrSortClass -250, wpSetSortAttribAvailable -258 


® wpModifyFSdrFlags WPFolder instance method 

(Warp only) 

P ■■■■■ ■ ■ ■ ■BB M M a MMMMa——————I—— 

Sets the flags describing the current state of a folder. 

SYNTAX 

BOOL wpModifyFldrFlags (ULONG ulFlags, ULONG uIFlagMask) 

PARAMETERS: 

ulFlags - input 

The folder flags to modify. OR together multiple flags to turn on or off 
more than one flag at once. The following are the documented folder 
flags: 

Folder Flags 

FOI_POPULATEDWITHALL 

FOI_POPULATEDWITHFOLDERS 

FOI_WORKAREA 

FOI_CHANGEFONT 

FOIJWAMINIMIZE 

FOI_WASTART ONREST ORE 

FOI_NOREFRESHVIEWS 

FOI_ASYN CREFRESH ON OPEN 

FOI_TREEPOPULATE 

FOI_REFRESHINPROGRESS 

FOI_FIRSTPOPULATE 

FOI_WAMCRINPROGRESS 

FOI_CNRBKGNDOLDFORMAT 

FOI_CHANGEICONBGNDCOLOR 

uIFlagMask - input 

The mask of flags indicating which will be set and which will be re¬ 
moved. For example, if ulFlags is FOI_WORKAREA I FOIJPOPULAT- 
EDWITHALL and uIFlagMask is FOI_POPULATEDWITHALL, 
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FOI_WORKAREA will be removed and FOI_POPULATEDWITHALL 
will be set. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any folder to set its current folder flags. The 
FOI_WORKAREA flag is persistent when the folder goes dormant. 
The populate flags are not. Calling this method is preferable to using 
wpSetFldrFlags. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpQueryFldrFlags -248, wpSetFldrFlags -255 


• wpPopuIate WPFolder instance method 

Awakens the contents of a folder. 

SYNTAX 

BOOL wpPopulate(ULONG ulReservecL, PSZ pszPath , BOOL 
fFoldersOnly ) 

PARAHETERS 

ulReserved - reserved 
Set this to zero. 
pszPath - input 

The fully qualified path of the folder being populated. Call 
wpOueryRealName on the folder object to obtain this string. 
fFoldersOnly - input 

If TRUE, the folder will only be populated with objects descendent 
from WPFolder. If FALSE, all objects will be awakened. 
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RETURNS 

TRUE—The call completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any folder object to populate 
its contents. If successful, wpPopulate will set the FOIJPOPULATED- 
W1THFOLDERS flag and, if fFoldersOnly is set to FALSE, the 
FOIJPOPULATEDWITHALL flag. If the folder is already populated, 
the call will return TRUE immediately. 

HOWTO OVERRIDE 

This method can be overridden to modify the contents of a folder. Call 
the parent method first. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpQueryContent -243, wpQueryFldrAttr -245, wpQueryFldrFlags -248, 
wpUnlockObject -65 

RESTRICTIONS/WARNINGS 

® wpPopulate will raise the lock count of each object contained in the 
folder by one (even if the folder is already populated). It is the ap¬ 
plication’s responsibility to use wpQueryContent to enumerate the 
contents and unlock each object when it is no longer needed (see 
the sample for wpQueryContent). 


€D wpQueryContent WPFolder instance method 

Enumerates the contents of a folder. 

SYNTAX 

WPObject * wpQueryContent (WPQbject* Object, ULONG ulOption) 

PARAMETERS 

Object - input 

A pointer to the object to use to search for the next object in the con¬ 
tent list of the folder. If ulOption is not set to QC_NEXT, this parame- 
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ter is ignored. If this object is not contained in this folder, 

wpQueryContent will return FALSE. 

ulOption - input 

Set to one of the following: 

Define Description 

OCJFIRST 0 The first object in the content list will be returned. 

QC_NEXT 1 The next object after Object will be returned. 

QC_LAST 2 The last object in the content list will be returned. 

RETURNS 

(nonzero value)—the pointer of an object contained in this folder. 
NULL—An error occurred. 

HOWTO CALL 

Call this method on a populated folder to query its contents. Call 
wpPopulate first to populate the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpPopulate -242 

SAMPLE CODE 

The following sample demonstrates how to call wpQueryContent to 
enumerate the contents of a folder. This can be done from any method 
override or function where a folder pointer is available. 

SOMAny *Folder / *Object, *NextObj; 

PSZ pszFileName; 

ULONG ulSize =0; 


/* Populate the OS/2 System Folder */ 

Folder = _wpclsQueryObjectFromPath(_WPFileSystem / "<WP_OS2SYS>"); 


if (Folder) 
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_wpQueryRealName(Folder, NULL, &ulSize, TRUE); 
if (ulSize) 

{ 

pszFileName = malloc(ulSize); 

_wpQueryRealName(Folder, pszFileName, &ulSize, TRUE); 
_wpPopulate(Folder, 0, pszFileName, FALSE); 
free(pszFileName); 

/* Loop through the contents of the folder and unlock the 

objects as we go because wpPopulate locked them each once. 

*/ 

Object = _wpQueryContent(Folder, NULL, QC_FIRST); 
while (Object) 

{ 

/* Do something with Object here... */ 

/* Get the next object pointer before unlocking Object. 

* There is a small chance that this Object might go to 

* sleep before we can query the next object. 

*/ 

NextObj = _wpQueryContent(Folder, Object, QC_NEXT); 
_wpUnlockObject(Object); 

Object = NextObj; 

} 

} 

_wpUnlockObject(Folder); 

} 


® wpQueryFIdrAttr WPFoIder instance method 

Returns the attributes of a folder’s view. 

SYNTAX 

ULONG wpQueryFIdrAttr (ULONG ulView) 

PARAMETERS 

ulView - input 

The folder view to query. Set ulView to one of the following: 
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Define Description 


OPEN_CONTENTS 

1 

Icon view 

OPEN_TREE 

101 

Tree view 

OPEN_DETAILS 

102 

Details view 


RETURNS 

The container attributes for the specified view. These are the view 
identifier flags used in the flWindowAttr field in the CNRINFO struc¬ 
ture for the container: 


Define 


Description 

CV_TEXT 

0x01 

Text view. Can be combined with CV FLOW. 

CVJNAME 

0x02 

Name view. Can be combined with CV_MINI and/or 
CVJFLOW. 

CVJCON 

0x04 

Icon view. Can be combined with CV_MINI. 

CVJDETAIL 

0x08 

Details view. 

CV_FLOW 

0x10 

Flowed view. 

CV_MINI 

0x20 

Use mini icons. 

CV_TREE 

0x40 

Tree view. Can be combined with CVJTEXT, 
CV_NAME, or CVJCON. 


HOWTO CALL 

Call this method on any folder to determine the container attributes 
for its views. Some of these attributes can be set by the user on the View 
pages of the settings notebook of the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h and pmstddlg.h 

SEE ALSO 

wpSetFldrAttr -253 
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® wpQyeryFSdrDetaiSsCIass WPFoIder instance method 

Returns the class used to define the columns of the details view of a 
folder. 

SYNTAX 

M_WPObject* wpOueryFldrDetailsClass( ) 

[PARAMETERS 

none 

RETURNS 

The pointer to the class object used for the details view of a folder. 

HOWTO CALL 

Call this method on any folder to determine which class is used to de¬ 
fine the columns for its details view. Regardless of which classes of ob¬ 
jects are contained in a folder, when a details view is opened, the folder 
will only display details columns defined by the class object returned in 
wpOueryFldrDetailsClass. This value can be set by the user on the 
third View page in the settings notebook of the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. Call wpSetFldrDetailsClass to 
change the class object. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpSetFldrDetailsClass -254 

RESTRICTIONS/WARNINGS 

© Note that the object returned from this method is a class object 
pointer not an instance pointer. Do not call instance methods with 
this pointer. 
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• wpQueryFidrFlags WPFoIder Instance method 

Returns the flags describing the current state of a folder. 

SYNTAX 

ULONG wpQueryFidrFlags ( ) 

PARAMETERS 

none 

RETURNS 

This object’s current folder flags. See wpModifyFldrFlags for the list of 
possible folder flags. 

HOWTO CALL 

Call this method on any folder to determine its current folder flags. 
The FOIJWORKAREA flag is persistent when the folder goes dor¬ 
mant. The populate flags are not. 

HOWTO OVERRIDE 

This method is generally not overridden. Call wpSetFldrFlags or 
wpModifyFldrFlags (Warp) to change the flags. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpModifyFldrFlags -241, wpSetFldrFlags -255 

RESTRICTIONS/WARNINGS 

© A folder will have the FOI_POPULATEDWITHFOLDERS flag but 
not the FOI_POPULATEDWITHALL flag when wpPopulate is 
called with the fFoldersOnly flag set to TRUE. The tree view for fold¬ 
ers calls wpPopulate in this fashion. 


• wpQueryFIdrFont WPFoIder Instance method 


Returns the font used for the text in a folder view. 
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SYNTAX 

PSZ wpQueryFldrFont(ULONG ulView) 

PARAMETERS 
ulView - input 


The view to query. 

This can be one of the following: 

Define 


Description 

OPEN_CONTENTS 

1 

Icon view 

OPEN_TREE 

101 

Tree view 

OPENED ETAILS 

102 

Details view 


RETURNS 

The pointer to the string with the font name and point size for this 
view. The format is the point size, followed by a period, followed by the 
font name. For example, 10 point Helv would be “lO.Helv”. 

HOWTO CALL 

Call this method to determine the font used for the text in a folder’s 
view. This value can be set by the user on the View pages in the settings 
notebook. 

HOWTO OVERRIDE 

This method is generally not overridden. Call wpSetFldrFont to 
change the font for a view. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpSetFldrFont -256 

RESTRICTIONS/WARNINGS 

$ Note that different folder views can have different fonts assigned to 
them, but multiple occurrences of the same view will have the same 
font. 




250 


Workplace Shell 


• wpQyeryFidrSortCSass WPFoIder instance method 

(Warp only) 


Returns the sort class for a folder. 

SYNTAX 

M_WPObject* wpQueryFldrSortClass( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the class object used for the sort functionality of a 
folder. 

HOWTO CALL 

Call this method on any folder to determine which class is used to de¬ 
fine the columns used for sorting. Regardless of which classes of ob¬ 
jects are contained in a folder, the Sort pulldown in the pop-up will 
only contain the sortable details columns defined by the class object re¬ 
turned by this method. This class can be set by the user on the Sort 
page in the settings notebook of the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. Call wpSetFldrSortClass to 
change the class object. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpSetFldrSortClass-257 

RESTRICTIONS/WARNINGS 

• Note that the object returned from this method is a class object 
pointer not an instance pointer. Do not call instance methods with 
this pointer. 
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# wpQueryFolder WPObject instance method (Warp only) 

Returns the folder that contains an object. 

SYNTAX 

WPObject* wpQueryFolder ( ) 

PARAMETERS 

none 

RETURNS 

The pointer to the folder that contains the object. 

HOWTO CALL 

Call this method on any object to determine its containing folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 


• wpQueryNextlconPos WPFolder instance method 

Returns the next icon position for an object being inserted into the 
icon view of a folder. 

SYNTAX 

PPOINTL wpQueryNextlconPos ( ) 

PARAMETERS 

none 


RETURNS 

A pointer to a POINTL structure (pg. 137) that contains the x and y 
coordinates for the next available slot in a nongridded icon view. 
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HOWTO CALL 

Call this method on any folder to determine the next position for an 
object to be placed in the folder’s nongridded icon view. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h and os2def.h 


• wpSetOetailsCoIumnVisibillty WPFolder Instance 

method (Warp only) 


Hides or unhides a details data column. 

SYNTAX 

BOOL wpSetDetailsColumnVisibility (ULONG index, BOOL Visible) 

PARAMETERS 

index - input 

The index of the details data column. 

Visible - input 

If set to TRUE, the column will be visible. If FALSE, the column will be 
hidden. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set a column in a folder’s details view as 
visible or invisible. The folder’s details view columns are determined 
by the folder’s details class. This class can be queried with 
wpQueryFldrDetailsClass. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 
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SEE ALSO 

wpclsOueryDetailsInfo -123, wpIsDetailsColumnVisible - 239, 
wpQueryFldrDetailsClass - 247 


# wpSetFIdrAttr WPFoider instance method 


Sets the attributes of a folder’s view. 

SYNTAX 

BOOL wpSetFIdrAttr (ULONG Att% ULONG ulView) 

PARAMETERS 

Attr- input 

The container attributes to set for the specified view. These are the 
flags used in the flWindowAttr field in the CNRINFO structure for the 
container. Only specify those flags relevant for the view. For example, 
do not use the CV_DETAILS flag if ulView is set to OPEN_TREE. See 
wpQueryFldrAttr for a list of attribute flags. 
ulView - input 

The folder view for which to set the attributes. Set ulView to one of the 
following: 


Define _ Description 


OPEN_CONTENTS 

1 

Icon view 

OPEN_TREE 

101 

Tree view 

OPEN_DETAILS 

102 

Details view 


RETURNS 

TRUE—The attributes were set successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any folder to set the container attributes for its 
views. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpfolder.h and pmstddlg.h 

SEE ALSO 

wpQueryFldrAttr -245 


• wpSetFIdrDetaiSsCIass WPFolder instance method 

Sets the class used to define the columns of the details view of a folder. 

SYNTAX 

BOOL wpSetFldrDetailsClass(M_WPObject * Class) 

PARAMETERS 

Class - input 

The class object pointer for the desired class. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any folder to specify which class is used to define 
the columns for its details view. Regardless of which classes of objects 
are contained in a folder, when a details view is opened, the folder will 
only display details columns defined by the class object specified by 
this method. This value can be set by the user on the third View page 
in the settings notebook of the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpQueryFldrDetailsClass -247 
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RESTRICTIONS/WARNINGS 

O Note that the Class parameter is a class object pointer not an instance 
pointer. 


® wpSetFSdrFlags WPFoSder Instance method 

Sets the flags that describe the current state of a folder. 

SYNTAX 

BOOL wpSetFldrFlags (ULONG ulFlags) 

PARAMETERS 

ulFlags - input 

This object’s current folder flags. See wpModifyFldrFlags for a list of 
possible flags. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any folder to set its current folder flags. The 
FOI_WORKAREA flag is persistent when the folder goes dormant. 
The populate flags are not. Since there are many folder flags that the 
system uses, always call wpQueryFldrFlags first to preserve those flags. 
In Warp, wpModifyFldrFlags is the preferred method for changing 
folder flags. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpModifyFldrFlags -241, wpQueryFldrFlags -248 
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• wpSetFidrFoiit WPFolder Instance method 

Sets the font used for the text in a folder view. 

SYNTAX 

BOOL wpSetFldrFont(PSZ pszFont ,ULONG ulView ) 

PARAMETERS 

pszFont - input 

The pointer to the string with the font name and point size. The for¬ 
mat is the point size, followed by a period, followed by the font name. 
For example, 10 point Flelv would be “lO.Helv”. 
ulView - input 

The view for which to set the font. This can be one of the following 

Define Description 


OPEN_CONTENTS 

1 

Icon view 

OPENJTREE 

101 

Tree view 

OPENJDETAILS 

102 

Details view 


RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method to set the font used for the text in a folder’s view. This 
value can be set by the user on the View pages in the settings notebook. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpOueryFldrFont -248 
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RESTRICTIONS/WARNINGS 

<§ Note that different folder views can have different fonts assigned to 
them, but multiple occurrences of the same view will have the same 
font. 


® wpSetFIdrSortClass WPFoIder Instance method 

(Warp only) 


Sets the sort class for a folder. 

SYNTAX 

BOOL wpSetFIdrSortClass (M_WPObject * Class) 

PARAMETERS 

Class - input 

The pointer to the class object to use for the sort functionality of the 
folder. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method on any folder to specify which class is to be used to de¬ 
fine the columns used for sorting. Regardless of which classes of ob¬ 
jects are contained in a folder, the sort pulldown in the pop-up will 
only contain the sortable details columns defined by this class object. 
This class can be set by the user on the Sort page in the settings note¬ 
book of the folder. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpQueryFldrSortClass -250 
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RESTRICTIONS/WARNINGS 

• Note that the Class parameter is a class object pointer not an instance 
pointer. 


• wpSetSortAttribAvaiSable WPFoider instance method 

(Warp only) 


Adds or removes a sort attribute for a folder’s Sort pulldown in the 
pop-up menu. 

SYNTAX 

BOOL wpSetSortAttribAvailable (ULONG index, BOOL Available) 

PARAMETERS 

index - input 

The index of the details data column. 

Available - input 

If set to TRUE, the details column will be available for sorting. If set to 
FALSE, the column will not be available. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to specify which sort attributes are avail¬ 
able to the user in the pop-up menu of a folder. These sort attributes 
are those defined by the folder sort class. This class can be queried with 
wpQueryFldrSortClass. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpclsQueryDetailsInfo -123, wpIsSortAttribAvailable -240, 
wpQueryFldrSortClass -250 
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Class Methods 


wpclsQueryActiveDesktop (Warp) returns the object pointer of the ac¬ 
tive desktop (pg. 259). 

wpclsQueryActiveDesktopHWND (Warp) returns the window handle 
of the active desktop (pg. 260). 

wpclsQuerylconBataN (Warp) returns the data of the open icon for a 
class (pg. 260). 

wpclsQuerylconN (Warp) returns the handle of the open icon for a 
class (pg. 262). 

wpclsQueryOpenFolders enumerates all the folders currently open in 
the system (pg. 262). 

wpclsInsertMultipleObjects (Warp) inserts multiple objects into the 
specified container (pg. 264). 

wpclsRemoveObjects (Warp) removes multiple objects from the speci¬ 
fied container (pg. 265). 


# wpclsQueryActiveDesktop WPOesktop class method 

(Warp only) 

Returns the object pointer of the active desktop. 

SYNTAX 

WPObject * wpclsQueryActiveDesktop ( ) 

PARAMETERS 

none 

RETURNS 

The object pointer of the active desktop. 

HOWTO CALL 

Call this method at any time on the _WPDesktop class object. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpdesk.h 

SEE ALSO: 

wpclsQueryActiveDesktopHWND -260 


• wpdsQueryActive DesktopHWND WPDesktop class 

method (Warp only) 

Returns the window handle of the active desktop. 

SYNTAX 

HWND wpclsQueryActiveDesktopHWND ( ) 

PARAMETERS 

none 

RETURNS 

The frame window handle of the active desktop. 

HOWTO CALL 

Call this method at any time on the _WPDesktop class object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdesk.h 

SEE ALSO 

wpclsQueryActiveDesktop -259 


# wpdsQuerylconDataN WPFoSder class method 

(Warp only) 


Returns the data of the open icon of a class. 
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SYNTAX 

ULONG wpclsQuerylconDataN (PICQNINFO conlnfo, ULONG 

ullconlndex) 

PARAMETERS 

plconlnfo - input/output 

A pointer to an ICONINFO structure (pg. 136) containing the re¬ 
quested icon data. If NULL is specified, the required size for the buffer 
is returned. 
ullconlndex - input 

The index for the requested icon. Only the number 1 is currendy sup¬ 
ported. 

RETURNS 

(nonzero value)—The size of the icon data for this class. 

0—An error occurred. 

HOWTO CALL 

Call this method at any time to obtain the icon data for the icon dis¬ 
played when a folder is opened. This method is also called by the sys¬ 
tem to determine this icon data. 

HOWTO OVERRIDE 

Override this method to specify the default icon data for your class. If 
plconlnfo is NULL, just return the required size for the data. If the 
ICON_DATA format will be used, include the size of the plconlnfo- 
>pIconData buffer as well. If plconlnfo is non-NULL, fill in the icon 
data for the class and return the total size. If the data in plconlnfo will 
be in the ICON_DATA format, set pIconInfo->p!conData to 
(PVOID) (plconlnfo+l). You do not need to call the parent method. 

OTHER INFO 

Include file: wpfolder.h and os2def.h 

SEE ALSO 

wpclsQueryIconData-124, wpclsQuerylconN -262 



262 


Workplace Shell 


® wpcSsQuerylcotiN WPFolder class method (Warp only) 
Returns the handle of the open icon of a class. 

SYNTAX 

HPOINTER wpclsQuerylconN (ULONG ullconlndex) 

PARAMETERS 

ullconlndex - input 

The index for the requested icon. Only the number 1 is currently sup¬ 
ported. 

RETURNS 

The handle of the open icon for this class. 

HOWTO CALL 

Call this method at any time to obtain the handle for the icon dis¬ 
played when a folder is opened. 

HOWTO OVERRIDE 

Override wpclsQuerylconDataN to specify the open icon for a folder 
subclass. 

OTHER INFO 

Include file: wpfolder.h and os2def.h 

SEE ALSO 

wpclsQuerylconDataN -260 

# wpcSsQueryOpenFoSders WPFolder class method 
Enumerates all the folders currently open in the system. 

SYNTAX 

WPFolder * wpclsQueryOpenFolders (WPFolder * Folder, ULONG 

ulOption, BOOL /Lock) 


PARAMETERS 

Folder - input 
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A pointer to the folder object to use to search for the next open folder. 
If ulOption is not set to QCJMEXT, this parameter is ignored. 
ulOption - input 
Set to one of the following: 


Define _ Description 


QQFIRST 

0 

The first open folder will be returned. 

OC_NEXT 

i 

The next open folder after Folder will be returned. 

OC_LAST 

2 

The last open folder will be returned. 


fJLock - input 

TRUE—Increment the lock count on the folder object returned. 
FALSE—Do not increment the lock count. 

RETURNS 

An object pointer for a folder in the system with an open view. 

HOWTO CALL 

Call this method at any time on the _WPFolder class object to enu¬ 
merate the folders currently open in the system. This method only re¬ 
turns folders with an open view of OPEN_CONTENTS, OPEN_TREE, 
or OPEN_DETAILS. If fLock is set to TRUE, call wpUnlockObject on 
the folder object pointers when they are no longer needed. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfolder.h 

SEE ALSO 

wpUnlockObject -65 

SAMPLE CODE 

The following sample is a function called QueryOpenFolders that sim¬ 
ply enumerates the open folders and displays their titles. 

#include <wpfolder.h> 


VOID QueryOpenFolders (VOID) 
{ 
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WPFolder *Folder, *NextFolder; 

PSZ pszTitle; 

CHAR szMessage[256]; 

/* enumerate the open folders in the system */ 

Folder = _wpclsQueryOpenFolders(_WPFolder, NULL, QC_FIRST, TRUE); 
while (Folder) 

{ 

pszTitle = _wpQueryTitie(Folder); 

/* warning: this code assumes the folder title will not exceed 

* the szMessage buffer. Applications should check the size of 

* the title before storing it in a buffer. 

*/ 

sprintf(szMessage, "%s is an open folder.", pszTitle); 
WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, szMessage, 
"Enumerating Open Folders", 0, MB_OK); 

/* get the next open folder first, then unlock this one. */ 
NextFolder = _wpclsQueryOpenFolders(_WPFolder, Folder, QC_NEXT, 

TRUE); 

_wpUnlockObject(Folder) ; 

Folder = NextFolder; 

} 

} 


• wpcIslnsertMuStlpleObjeets WPObJect class method 

(Warp only) 


Inserts multiple objects into the specified container. 

SYNTAX 

BOOL wpclsInsertMultipleObjects(HWND hwndCnr, PPOINTL 

pptllcon, PYOIB pObjectArray, 
PVOIB pRecordParent ,, ULONG 
NumRecords) 

PARAMETERS 

hwndCnr - input 

The window handle of the container control in which to insert the ob¬ 
jects. The container must be created from a thread running on the 
Workplace Shell process. 


Folder Objects 


265 


pptllcon - input 

A pointer to a POINTL structure (pg. 137) which contains the icon 
postion at which to insert the first object. This pointer must be set, but 
the POINTL structure can contain zeros if the view for this container 
does not support icon positions or the next available position should 
be used. 

pOhjectArray - input 

An array of pointers to MINIRECORDCORE structures for each object 
to insert. Call wpQueryCoreRecord on an object to determine its 
record pointer. 
pRecordParent - input 

A pointer to the parent record for these objects. If hwndCnr is not a 
tree view or these records do not have a parent, set this to NULL. 
NumRecords - input 

The number of records in pOhjectArray . 

RETURNS 

TRUE—The objects were added successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to add multiple objects to a container. 
This method has the same effect as calling wpCnrlnsertObject multi¬ 
ple times, but is faster. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpclsRemoveObjects -265, wpCnrlnsertObject -233, 
wpCnrRemoveObject -234, wpOueryCureRecord -112 


# wpclsRemoveObjects WPObJect class method 

(Warp only) 


Removes multiple objects from the specified container. 
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SYNTAX 

BOO L wpc 1 sRe in oveO bj e c ts (HWND hwndCnr ,; PYOID pRecordArray, 

ULONG NumRecords, BOOL Remove All) 

PARAMETERS 

hwndCnr - input 

The window handle of the container control from which to remove the 
objects. 

pRecordArray - input 

An array of pointers to MINIRECORDCORE structures for each object 
to remove. Call wpQueryCoreRecord on an object to determine its 
record pointer. 

NumRecords - input 

The number of records in pRecordArray . 

Remove All - input 

If set to TRUE, all objects are removed from hwndCnr. Otherwise, only 
the objects specified in pRecordArray are removed. 

RETURNS 

TRUE—The objects were removed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to remove multiple objects from a con¬ 
tainer. These objects must have been added to the container using ei¬ 
ther wpCnrlnsertObject or wpclsInsertMultipleObjects. This method 
has the same effect as calling wpCnrRemoveObject multiple times, but 
is faster. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include file: wpobject.h and pmstddlg.h 

SEE ALSO 

wpclsInsertMultipleObjects -264, wpCnrlnsertObject -233, 
wpCnrRemoveObject -234 



RECORPINSERT __ (24 bytes) 

cb (ULONG) 0 

The size of this structure, including cb itself. 

pRecordOrder (PRECORDCORE) 4 

The record after which to insert this record. Specify CMA_FIRST to place the record at the 
beginning, CMA_LAST to place the record at the end, or the record pointer of any object 
already in the container. 

pRecordLParent (PRECORDCORE) 8 

The parent record under which to place the record. This can be NULL and is ignored for 
non tree views. 

ITnvalidateReeord (ULONG) 12 

Specify TRUE and the container will be invalidated when the record is inserted. Specify 
FALSE and the container will not be invalidated. 

zOrder (ULONG) 16 

CMA_TOP places the record on top of other objects. CMA_BOTTOM places it under other 
objects. 

cRecordsInsert (ULONG) 20 

The number of root level records to be inserted. This value must be greater than 0. 

Used by: wpCnrlnsertObject -233 
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Program Classes 

T here are two types of objects that represent programs in the 
Workplace Shell: program file objects and program objects. The 
objects that represent the actual executable files are program file ob¬ 
jects (WPProgramFile) which are descendants of WPFileSystem. How¬ 
ever, users interact primarily on their desktops with program objects 
(WPProgram) which are descendants of WPAbstract. Program objects 
are more useful because they can reside anywhere on the desktop and 
point to a program file anywhere in the file system. Program files, on 
the other hand, reside in the folder representing the directory where 
the executable resides in the file system. 

WPProgram and WPProgramFile have most of the same methods. 
Although Workplace Shell does not use multiple inheritance, both 
program classes define methods with the same names and share com¬ 
mon code. 
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Associations 

Workplace supports file associations as they were defined by applica¬ 
tions for OS/2 version 1.3. Programs can list which types of data files 
are supported through an ASSOCTABLE defined in its resource file. 
When a program object or a program file object is awakened, the ob¬ 
ject registers the association information stored in the executable with 
the system. Then a template for each entry from the ASSOCTABLE is 
created in the Templates folder and each file of the associated type or 
extension will have the executable listed in the Open pulldown of its 
pop-up menu. Each program to which the data file is associated is con¬ 
sidered to be a view of the data file object. 

PM programs can now set associations between programs and data 
files using WinSetObjectData and the ASSOCTYPE and ASSOCFILTER 
setup string keywords (see Appendix A). Workplace applications can 
also set associations with the wpSetAssociationType and wpSetAssocia- 
tionFilter methods. These mechanisms eliminate the need for the 
ASSOCTABLE resource. 

An alternative to associations would be to create a WPDataFile 
subclass that overrides wpclsQuerylnstanceType (pg. 226) and/or 
wpclsOuerylnstanceFilter (pg. 227) to designate which types of files 
are of this class. Instances of such a subclass could have a pop-up 
menu item that would run the executable with the data file as a pa¬ 
rameter. Another alternative is for the user to simply use the Menu 
page of the settings notebook of file system objects to build his or her 
own associations. 

Restrictions and Warnings 

m Menu items in a data file’s pop-up menu can be removed through 
the use of the wpQueryAssociatedProgram method. 
m When a program is opened as a result of the user opening an associ¬ 
ated file, dragging a file onto the program, or summoning the pro¬ 
gram from the menu of another object, the program object is not no¬ 
tified that an open is occurring (the wpOpen method is not called). 
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instance Methods 


wpConfirmKeepAssoc (Warp) confirms whether file extensions of 
data files can be renamed (pg. 270). 

wpQueryAssociatedFilelcoii (Warp) returns the icon of the default as¬ 
sociated program object of a data file (pg. 271). 

wpQiieryAssociatedProgram returns the associated program of a data 
file given the view’s pop-up menu ID (pg. 272). 

wpQueryAssociationFilter returns the list of file name filters indicat¬ 
ing which data files are associated with a program (pg. 275). 
wpQueryAssociationType returns the list of file types indicating which 
data files are associated with a program (pg. 276). 
wpQueryProgBetails returns the program details for an object 
(pg. 277). 

wpQueryScreenGroupIB (Warp) returns the screen group ID for a 
running program (pg. 279). 

wpSetAssocIatedFilelcon sets the icon of a data file to be the icon of its 
associated program (pg. 280). 

wpSetAssociationFilter sets the list of file name filters indicating which 
data files are associated with a program (pg. 281). 
wpSetAssociationType sets the list of file types indicating which data 
files are associated with a program (pg. 282). 
wpSetProgBetails sets the program details for an object (pg. 283). 


® wpConfirmKeepAssoc WPFISeSystem instance method 

(Warp only) 


Confirms whether file extensions of data files can be renamed. 

SYNTAX 

ULONG wpConfirmKeepAssoc ( ) 

PARAMETERS 

none 


RETURNS 

The response from the user: 
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Define Description 

KEEP_RENAMEFILESWITHEXT 1 Rename the extension of the file 

and add the association to the 
pop-up menu. 

DISCARD_RENAMEFILESWITHEXT 2 Rename the extension of the file 

and discard the association. 

CANCEL_RENAMEFILESWITHEXT 3 Do not rename the extension of 

the file. 


HOWTO CALL 

This method can be called on any file object to request confirmations 
from the user when the extension of a file with associations is about to 
be changed. 

HOWTO OVERRIDE 

This method can be overridden to change its default behavior. 

OTHER INFO 

Include files: wpfsys.h 


® wpQyeryAssociatedFiIelcoo WPDataFile instance 
__method (Warp on By) 


Returns the icon of the default associated program object of a data file. 

SYNTAX 

HPOINTER wpQueryAssociatedFile!con( ) 

PARAMETERS 

none 

RETURNS 

The handle of the icon representing this file’s default associated pro¬ 
gram. 

HOWTO CALL 

This method can be called on any data file object. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpSetAssociatedFilelcon -280 


• wpQueryAssociatedProgram WPDataFiSe 

instance method 


Returns the associated program of a data file given the view’s pop-up 
menu ID. 

SYNTAX 

WPObject * wpQueryAssociatedProgram (ULONG ulView, PULONG 

pulHowMatched, PSZ pszMatch- 
String, ULONG cbMatchString, 
PSZ pszDefaultType) 


PARAMETERS 

ulView - input 

The view of the data file. Note that data file views, other than settings, 
have the same numeric value as the pop-up menu items in the Open 
submenu. These view IDs can be queried by sending menu control 
messages to the hwndMenu parameter passed into wpModifyPopup- 
Menu. Set ulView to OPEN_RUNNING to get the default association. 
pulHowMatched - output 

A pointer to a ULONG which, upon return, will contain one of the fol¬ 
lowing values: 

Value Description! _ 

0 The view is a program added by the menu page of the settings 

notebook. 

1 The view is an association to a program from a match of a name 

filter. 


2 


The view is an association to a program from a match of a type. 
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pszMatchString- input/output 

A pointer to a string which, upon return, will contain the filter or type 

that caused this file to be associated with the program. The first byte of 

the string will be set to ‘\0’ if *pulHowMatched is not 1 or 2. 

cbMatchString - input 

The size of the pszMatchString buffer. 

pszDefaultType - input 

A pointer to a string containing the default type that should be used to 
search for matches if the data file has no real type. Set pszDefaultType 
to NULL to prevent the system from using a default type if this object 
has no type. Set it to -1 to allow the system to use the default type if this 
object has no type. 

RETURNS 

(nonzero value)—The pointer to the WPProgram or WPProgramFile 
object to which this file is associated. 

NULL—No association was found or an error occurred. 

HOWTO CALL 

This method can be called on any data file object to query the pro¬ 
gram objects associated with the object’s views. 

HOWTO OVERRIDE 

This method can be overridden if a data file subclass defines its own 
view IDs that represent some type of program association. wpOuery- 
AssociatedProgram is called by the system each time a view other than 
settings is selected from the Open pulldown of the pop-up menu. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpModifyPopupMenu -199, wpOpen -160, 
wpQueryAssociationFilter -275, wpOueryAssociationType -276, 
wpSetAssociationFilter -281, wpSetAssociationType -282 

RESTRICTIONS/WARNINGS 

© This method cannot be called with a NULL pointer for the pszMatch¬ 
String parameter to query the needed size for the buffer. The appli¬ 
cation must provide a very large buffer (256 should be large 
enough) to ensure it will fit. If the buffer is not large enough, the 
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method will still complete successfully, but pszMatchStringwill not be 
set. 

• The return code from this method will be either a WPProgram or a 
WPProgramFile instance. Be sure to check the class of the object 
when calling methods that are specific to one of these classes. 

• Be sure to call wpUnlockObject on the object pointer returned 
from this method when it is no longer needed. 

SAMPLE CODE 

The following sample demonstrates how to call wpQueryAssociated- 
Program from a wpOpen override to determine the associated pro¬ 
gram that will be opened. 

SOM_Scope HWND SOMLINK myf_wpOpen(MyFile *somSelf,HWND hwndCnr, 

ULONG ulView,ULONG param) 

{ 

WPObject *Program; 

ULONG ulHowMatched; 

CHAR szMatchString[256], szMessage[256]; 

PSZ pszTitle; 


if (ulView |# OPEN_SETTINGS) 

{ 

Program = _wpQueryAssociatedProgram(somSelf, ulView, 

&u1HowMatched, 
szMatchString, 
sizeof(szMatchString), 
(PSZ) -1); 

if (Program) 

{ 

pszTitle = _wpQueryTitie(Program); 

sprintf(szMessage, "%s is associated with this file using" 
"view %d.", 
pszTitle, ulView); 

WinMessageBox(HWND_DESKTOP, HWND_DESKTOP, szMessage, 
"Opening a Data File", 0, MB_OK); 

_wpUnlockObject(Program); 

} 

} 

return (parent_wpOpen(somSelf,hwndCnr,ulView,param)); 



• wpQueryAssociation Filter WPProgram(File) 

instance method 

Returns the list of file name association filters for a program. 

SYNTAX 

PSZ wpQueryAssociationFilter ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—The pointer to the string containing a list of asso¬ 
ciation filters for this program. Each filter is separated by a comma. 
For example, the list of filters for the OS/2 System Editor is 
“*.TXT,*.DOC”. 

NULL—This program does not have a list of association filters or an 
error occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or 
WPProgramFile object. If the source file where this method is called 
includes both wppgm.h and wppgmf.h and/or the class of the object 
could be either WPProgram or WPProgramFile, call lookup_wp- 
QueryAssociationFilter instead of _wpQueryAssociationFilter. This will 
cause SOM to use name lookup to guarantee the correct method is 
called. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h and wppgmf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpQueryAssociationType -276, 
wpSetAssociationFilter -281, wpSetAssociationType -282 
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• wpQueryAssociationType WPProgram(FiSe) 

instance method 


Returns the list of file types associated with a program. 

SYNTAX 

PSZ wpQueryAssociationType ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—The pointer to the string containing a list of associ¬ 
ated types for this program. Each type is separated by a comma. For ex¬ 
ample, the list of types for the OS/2 System Editor is “OS/2 Command 
File,DOS Command File,Plain Text”. 

NULL—This program does not have a list of associated types or an er¬ 
ror occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or 
WPProgramFile object. If the source file where this method is called 
includes both wppgm.h and wppgmf.h and/or the class of the object 
could be either WPProgram or WPProgramFile, call lookup_wp- 
QueryAssociationType instead of _wpQueryAssociationType. This will 
cause SOM to use name lookup to guarantee the correct method is 
called. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h and wppgmf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpQueryAssociationFilter -275, 
wpSetAssociationFilter -281, wpSetAssociationType -282 



wpQueryPr ogPetails WPProgram(Flle) instance method 

Returns the program details for an object. 

SYNTAX 

BOOL wpQueryProgDetails (PPROGDETAXLS pProgDetails, PIJLONG 

pulSize) 

PARAMETERS 

pProgDetails - input/output 

A pointer to a buffer that will contain the PROGDETAILS (pg. 284) 
structure and the memory needed for any strings in the program de¬ 
tails. Do not just pass the address of a buffer that is only the size of the 
PROGDETAILS structure. Pass NULL in this parameter and the re¬ 
quired size will be returned in pulSize. 
pulSize- input/output 

A pointer to a ULONG which, upon return, will contain the size of the 
program details for this object. If pProgDetails is non-NULL, *pulSize 
should be set by the caller to the size of the pProgDetails buffer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or WPPro- 
gramFile object. If the source file where this method is called includes 
both wppgm.h and wppgmf.h and/or the class of the object could be 
either WPProgram or WPProgramFile, call lookup_wpQueryProg- 
Details instead of _wpQueryProgDetails. This will cause SOM to use 
name lookup to guarantee the correct method is called. The system 
will call this method to determine the program details to pass to 
WinStartApp when wpOpen is called with ulView set to OPEN_RUN- 
NING. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h, wppgmf.h, Define: 

and pmshl.h INCL_WINPROGRAMLIST 
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SEE ALSO 

wpOpen -160, wpSetProgDetails -283 

NOTES 

Call wpQueryProgDetails before calling wpSetProgDetails to preserve 
any details you do not wish to modify 

SAMPLE CODE 

The following sample demonstrates how to query, modify, and then set 
the details of a program object. The parameter string for the EPM ed¬ 
itor will be changed to point to c:\autoexec.bat. This code can also be 
used for program file objects. 

ttdefine INCL_WINPROGRAMLIST 


#include <os2.h> 


#include <wppgm.h> 


VOID ChangeProgDetails(VOID) 


PPROGDETAILS 

ULONG 

WPProgram 

HOBJECT 

CHAR 


pProgDetails; 
ulSize; 

*Program; 
hProgram; 
szParameters[ ] 


"C:\\AUTOEXEC.BAT"; 


/* get the object handle for the EPM editor */ 
hProgram = WinQueryObject("<WP_EPM>"); 
if (hProgram) 


/* get the SOM pointer for the program object */ 
Program = _wpclsQueryObject(_WPObject, hProgram); 


/* call wpQueryProgDetails passing NULL for the pointer to get 
the size */ 

if (Program && _wpQueryProgDetaiIs(Program, NULL, &ulSize)) 

{ 

/* allocate the buffer */ 

pProgDetails f (PPROGDETAILS) _wpAllocMem(Program, ulSize, 

NULL); 

if (pProgDetails) 

{ 
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/* do the actual query of the prog details */ 
if (_wpQueryProgDetaiIs(Program, pProgDetails, &ulSize)) 
{ 

/* pszParameters can be set to a local variable 
* because Workplace will copy the string. 

*/ 

pProgDetails->pszParameters = szParameters; 
_wpSetProgDetails(Program, pProgDetails); 

_wpSaveDeferred(Program); 

} 

/* this buffer is no longer needed */ 

_wpFreeMem(Program, (PBYTE) pProgDetails); 

} /* if pProgDetails */ 

} 

if (Program) 

_wpUnlockObject(Program); 

} /* if hProgram */ 

} 


# wpQueryScreenGroypiD WPObfeet instance method 

(Warp only) 


Returns the screen group ID for a running program. 

SYNTAX 

USHORT wpQueryScreenGroupID (USHORT usPrevSgld) 

PARAMETERS 

usPrevSgld - input 

If set to 0, the screen group ID of the first running program is re¬ 
turned. If set to an ID previously returned from this method, the ID of 
the next running program is returned. 

RETURNS 

The screen group ID for a program running as a view of this object. 

HOWTO CALL 

This method can be called at any time. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 


® wpSetAssociatedFiieicoo WPDataFile instance method 

Sets the icon of a data file to the icon of its associated program. 

SYNTAX 

VOID wpSetAssociatedFilelcon ( ) 

PARAMETERS 

none 

RETURNS 

none 

HOWTO CALL 

Call this method at any time to notify the data file to set its icon to that 
of its default associated program. The system will call this method on 
data files when their default associations change. This method will not 
be called if the data file has a customized icon (see wpSetlconData) or 
if it is a descendant of WPProgramFile. 

HOWTO OVERRIDE 

Override this method to prevent the system from setting the icon of a 
data file to that of its default associated program. 

OTHER INFO 

Include: wpdataf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpSetlconData -120 
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• wpSetAssociationFilter WPProgram(FiSe) 

instance method 


Sets the list of file name association filters of a program. 

SYNTAX 

BOOL wpSetAssociationFilter (PSZ pszFilter) 

PARAMETERS 

pszFilter - input 

A pointer to the string containing a list of association filters for this 
program. Each filter is separated by a comma; for example, 
“*.C,*.CPP”. The system will make a copy of this string; therefore, it 
can be freed after this call. 

RETURNS 

TRUE—The association filter was set. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or 
WPProgramFile object. If the source file where this method is called 
includes both wppgm.h and wppgmf.h and/or the class of the object 
could be either WPProgram or WPProgramFile, call lookup_wp- 
SetAssociationFilter instead of _wpSetAssociationFilter. This will cause 
SOM to use name lookup to guarantee the correct method is called. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h and wppgmf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpQueryAssociationFilter -275, 
wpQueryAssociationType -276, wpSetAssociationType -282 
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• wpSetAssociationType WPProgram(File) 

instance method 


Sets the list of file types associated with a program. 

SYNTAX 

BOOL wpSetAssociationType (PSZ pszType) 

PARAMETERS 

pszType - input 

The pointer to the string containing a list of associated types for this 
program. Each type is separated by a comma; for example “C Code, 
Assembler Code”. The system will make a copy of this string; therefore, 
it can be freed after this call. 

RETURNS 

TRUE—The type was set. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or WPPro- 
gramFile object. If the source file where this method is called includes 
both wppgm.h and wppgmf.h and/or the class of the object could be 
either WPProgram or WPProgramFile, call 1 ookup_wpSetAssociation- 
Type instead of _wpSetAssociationType. This will cause SOM to use 
name lookup to guarantee the correct method is called. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h and wppgmf.h 

SEE ALSO 

wpQueryAssociatedProgram -272, wpQueryAssociationFilter -275, 
wpQueryAssociationType -276, wpSetAssociationFilter -281 
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® wp Set Prog Details WPProgram(Fsle) instance method 

Sets the program details for an object. 

SYNTAX 

BOOL wpSetProgDetails (PPROGDETAILS pProgDetails) 

PARAMETERS 

pProgDetails - input 

A pointer to a buffer containing the PROGDETAILS (pg. 284) struc¬ 
ture. The system will make a copy of the structure and all strings it 
points to; therefore, it can be freed after this call. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any WPProgram or 
WPProgramFile object. If the source file where this method is called 
includes both wppgm.h and wppgmf.h and/or the class of the object 
could be either WPProgram or WPProgramFile, call lookup_wpSet- 
ProgDetails instead of jwpSetProgDetails. This will cause SOM to use 
name lookup to guarantee the correct method is called. The system 
will pass this data to WinStartApp when wpOpen is called with ulView 
set to OPEN RUNNING. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppgm.h, wppgmf.h, Define: 

and pmshl.h INCL WINPROGRAMLIST 


SEE ALSO 

wpOpen -160, wpOueryProgDetails -277 

NOTES 

Call wpQueryProgDetails before calling wpSetProgDetails to preserve 
any details that you do not wish to modify. 
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Programs and Associations: Structures 


PROGDETAILS 





Length (ULONG) 0 

The size of the PROGDETAILS structure (that is, sizeof(PROGDETAILS) ). Note that this 
size is different than the size parameter for wpQueryProgDetails which includes the size re¬ 
quired for the string pointers as well. 

progt (PROGTYPE) 4 

A PROGTYPE structure. 

pszTitle (PSZ) 12 

The title for the running program. This field can be set to NULL. 

pszExecutable (PSZ) 16 

The file name of the program executable. This field can be set to NULL. 

pszParameters (PSZ) 20 

The parameter string to pass to the executable. Each parameter is separated by a space. This 
field can be set to NULL. 

pszStartupBir (PSZ) 24 

The working directory for the program. The system will first change directories to the path 
specified in this field and then execute the program. This field can be set to NULL. 

pszlcon (PSZ) 28 

The file name of the icon to set for this program. This field can be set to NULL. 

pszEnviroiiment (PSZ) 32 

A super string of environment strings. Each string is separated by a ‘\0’ character and the en¬ 
tire super string is terminated with two ‘\0’ characters. This field can be set to NULL. 

swplnitial (SWP) 36 

The initial size and position of the program. 

Used by: wpQueryProgDe tails -277, wpSetProgDetails -283 




proge (PROGCATEGORY) 

The program category for this program. This can be one of the following values: 


0 
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Define _ 

PROGJDEFAULT 0 

PROGJFULLSCREEN 1 

PROG_WINDOWABLEVIO 2 

PROG_PM 3 

PROG_VDM 4 

PROGJWINDOWEDVDM 7 

PROG_31_STDSEAMLESSVDM 15 

PRO G_3 l_STDSEAMLESSCOMMON 16 

PROG_31_ENHSEAMLESSVDM 17 

PROG_3 l_ENHSEAMLESSCOMMON 18 

PROG_31_ENH 19 

PROG_31_STD 20 


fbVisible (ULONG) 4 

Program visibility flags: 

Define _ 

SHE_VISIBLE 0x00 

SHE_INVISIBLE 0x01 

Used by: PROGDETAILS structure 



Disk Objects 


T he root directories for each drive in the system are instances of the 
WPRootFolder class which is a subclass of WPFolder; these objects 
are never visible to the user. A corresponding WPDisk object is placed 
in the Drives folder for each root folder in the system. WPDisk is de¬ 
scended from WPAbstract, and its instances are used to represent root 
folder objects and to enable the user to display and manipulate root 
folders. Since every folder on the desktop must be a subdirectory of 
the Desktop path (such as C:\Desktop), the extra level of indirection 
provided by WPDisk is necessary to make the contents of root folders 
accessible from the Desktop. 
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Restrictions and Warnings 

© The methods wpEjectDisk, wpLockDrive, and wpQueryDriveLock- 
Status can only be called on WPBisk objects that represent drives 
that support this functionality. 

© Do not call wpPopulate on a WPDisk object. WPDisk is not a de¬ 
scendant of WPFolder and does not support this method. Folder 
manipulation methods should be called on the corresponding 
WPRootFolder object. 


instance Methods 


wpEjectDisk ejects removable media from a drive that supports this 
feature (pg. 287). 

wpIsDiskSwapped (Warp) returns whether the removable media of a 
file system object has been swapped (pg. 288). 

wpLockDrive locks or unlocks removable media in a drive that sup¬ 
ports this feature (pg. 289). 

wpQueryBisk (Warp) returns the disk object representing the drive of 
a file system object (pg. 290). 

wpQueryDriveLockStatus returns the lock status of a drive (pg. 291). 
wpQueryLogicalDrive returns the logical drive number this object rep¬ 
resents (pg. 292). 

wpQueryRootFolder returns the corresponding root folder object for 
this disk object (pg. 293). 

wpSetCorrectBisklcon (Warp) notifies a disk object to set its icon 
based on its media type (pg. 293). 


® wpEjectDisk WPDisk instance method 


Ejects removable media from a drive that supports this feature. 

SYNTAX 

ULONG wpEjectDisk( ) 
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PARAMETERS 

none 

RETURNS 

0—The call completed successfully. 

(nonzero value)—An error occurred. This value is the return code 
from the call to DosDevIOCtl. 

HOWTO CALL 

This method can be called at any time on any WPDisk object that sup¬ 
ports ejecting removable media. DosDevIOCtl will be called with cate¬ 
gory IOCTL DISK and function 40 to perform this action. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpLockDrive -289, wpQueryDriveLockStatus -291 


9 wpIsDiskSwapped WPFileSystem instance method 

(Warp only) 


Returns whether the removable media of a file system object has been 
swapped. 

SYNTAX 

BOOL wpIsDiskSwapped ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The media has been swapped. 

FALSE—No swapping has occurred. 
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HOWTO CALL 

This method can be called at any time on any file system object. Do not 
call this method on a WPDisk object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpQueryDisk -290 


® wpLockBrive WPDisk instance method 


Locks or unlocks removable media in a drive that supports this feature. 

SYNTAX 

ULONG wpLockDrive(BOOL fLock) 

PARAMETERS 

fLock - input 

TRUE—Lock the drive. 

FALSE—Unlock the drive. 

RETURNS 

0—The call completed successfully. 

(nonzero value)—An error occurred. This value is the return code 
from the call to DosDevIOCtl. 

HOWTO CALL 

This method can be called at any time on any WPDisk object that sup¬ 
ports locking and unlocking removable media. DosDevIOCtl will be 
called with category IOCTL_DISK and function 40 to perform this ac¬ 
tion. 


HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpEjectDisk -287, wpQueryDriveLockStatus -291 

NOTES 

« Call wpQueryDriveLockStatus on a WPDisk object to determine if 
the drive supports locking and unlocking removable media. 


• wpQueryDIsk WPFileSystem instance method 

(Warp only) 

Returns the disk object representing the drive of a file system object. 

SYNTAX 

WPDisk * wpQueryDisk( ) 

PARAMETERS 

none 

RETURNS 

The disk object that represents the drive where the file system object 
resides. 

HOWTO CALL 

This method can be called at any time on any file system object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpfsys.h 

SEE ALSO 

wpIsDiskSwapped -288 



Disk Objects 


291 


RESTRICTIONS/WARNINGS 

• Although the prototype for this method in wpfsys.h specifies a re¬ 
turn type of WPFileSystem*, this method returns a WPDisk* (both 
are defined as SOMAny*). 


# wpQueryBnveLockStatus WPDisk instance method 

Returns the lock status of a drive. 

SYNTAX 

ULONG wpQueryDriveLockStatus(PULONG pulLockStatus , PULONG 

pulLockCount) 


PARAMETERS 

pulLockStatus - input/output 

A pointer to a ULONG which, upon return, will contain the following 
information about the lock status of the drive: 


Bits 0 - 1 : 


Bit 2 : 
Bits 3-31: 


0 The lock and unlock functions are not supported. 

1 The drive is locked. 

2 The drive is unlocked. 

3 The lock function is supported but the status of 
the drive cannot be determined. 

0 The drive is empty. 

1 There is media in the drive. 

(reserved) 


pulLockCount - currently unsupported 

RETURNS 

0—The call completed successfully. 

(nonzero value)—An error occurred. This value is the return code 
from the call to DosDevIOCtl. 


HOWTO CALL 

This method can be called at any time on any WPDisk object. 
DosDevIOCtl will be called with category IOCTLJDISK and function 
66 to perform this action. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpEjectDisk -287, wpLockDrive -289 


# wpQueryLogicalDrive WPDisk Instance method 

Returns the logical drive number this object represents. 

SYNTAX 

ULONG wpQueryLogicalDrive ( ) 

PARAMETERS 

none 

RETURNS 

The logical drive number of this disk object: 1 = A, 2 = B, and so on. 

HOWTO CALL 

This method can be called at any time on any WPDisk object to deter¬ 
mine which drive it represents. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpQueryRootFolder -293 
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• wpQueryRootFoider WPDisk instance method 

Returns the corresponding root folder object for a disk object. 

SYNTAX 

WPRootFolder * wpQueryRootFoider ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—The object pointer for the root folder. 

HOWTO CALL 

This method can be called at any time on any WPDisk object to deter¬ 
mine which root folder it represents. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpQueryLogicalDrive -292 


® wpSetCorrectDiskicon WPDisk instance method 

(Warp only) 


Notifies a disk object to set its icon based on its media type. 

SYNTAX 

BOOL wpSetCorrectDiskicon ( ) 

PARAMETERS 


none 
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RETURNS 

TRUE—The icon was set. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called on any disk object. 

HOWTO OVERRIDE 

Override this method to specify the icon for a disk object. Call 
wpQueryLogicalDrive to determine which drive this disk object repre¬ 
sents. 

OTHER INFO 

Include files: wpdisk.h 

SEE ALSO 

wpQueryLogicalDrive -292 
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Shadow Objects 


A shadow is an object whose sole function is to reference other ob¬ 
jects. The WPShadow class overrides practically every method de¬ 
fined by WPObject and usually calls the same method with the same 
parameters on the object it is linked to. For example, if you open the 
settings of a shadow of a folder object, the shadow’s wpOpen override 
is called, which then calls wpOpen on the folder. Therefore, it is the 
folder that is actually opening the settings view. The object that a 
shadow references is called the original object. 

Shadows are very useful for users who want to have an object on 
the desktop that points to an object somewhere else in the file system. 
It is not possible to edit the path on the file page of a file system object, 
but it is possible to create a shadow of any object and place it anywhere 
on the desktop. 
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Restrictions and Warnings 

@ Shadows are descendants of WPAbstract and, like other abstract ob¬ 
jects, cannot be copied onto the network or removable media. 

• Since shadows are WPAbstract descendants, it may not be possible to 
call methods on a shadow that are supported by the object the 
shadow is linked to. Only the common WPObject methods or 
WPShadow methods can be called on a shadow object. 


instance Methods 


wpCreateShadowObjectExt (Warp) creates a shadow of an object using 
the specified WPShadow subclass (pg. 296). 

wpQueryShadowedObject returns the pointer of the object to which 
this shadow refers (pg. 298). 

wpSetLinkToObject (Warp) sets the link between a shadow and an¬ 
other object (pg. 299). 

wpSetShadowTitle sets the title of a shadow to a string different from 
the title of the original object (pg. 300). 


# wpCreateShadowObjectExt WPObject instance 

method (Warp only) 


Creates a shadow of an object using the specified WPShadow subclass. 

SYNTAX 

WPObject * wpCreateShadowObjectExt(WPFolder * Folder, BOOL fLock, 

PSZ pszSetup, M_WPObject * 
shadowClass) 


PARAMETERS 

Folder - input 

The object pointer of the folder in which to place the shadow. Some 
methods for obtaining folder object pointers are wpclsQueryFolder, 
wpclsQueryObject, and wpclsQueryObjectFromPath. 
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fLock - input 

TRUE—Increment the lock count of the shadow object returned by 
this method. 

FALSE—Do not increment the lock count. 
pszSetup - input 

The initial settings for the new shadow object in the form of a setup 
string. A setup string is a list of keyname value pairs separated by semi¬ 
colons which is parsed by the object for initialization. Specify NULL to 
use the object’s defaults. See Appendix A for the list of available key¬ 
name value pairs for the predefined Workplace Shell classes. For more 
information on setup strings, see wpSetup (pg. 63). 
shadowClass - input 

The class of the new shadow object. This must be _WPShadow or the 
class object pointer of any subclass of WPShadow. 

RETURNS 

(nonzero value)—A pointer to the new shadow object. 

NULL—An error occurred. 

HOWTO CALL 

This method can be called at any time to create a shadow of an object. 
Use this method instead of wpCreateShadowObject if a setup string is 
desired or if a different shadow class is required. A USAGEJLINK item 
will be added to the in-use list of the original object. See Chapter 6 for 
more information on in-use lists. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsQueryFolder -74, wpclsOueryObject -75, 
wpclsQueryObjectFromPath -76, wpAddToObjUseList -145, 
wpCreateShadowObject -50, wpQueryShadowedObject -298, 
wpSetup -63, wpUnlockObject -65 
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NOTES 

Pass TRUE for the fLock parameter if you are going to access the 
shadow object pointer after calling wpCreateShadowObjectExt. When 
the pointer is no longer needed, call wpUnlockObject. 


# wpQueryShadowedObJect WPShadow instance method 


Returns the pointer of the object to which this shadow refers. 

SYNTAX 

WPObject * wpQueryShadowedObject(BOOL fLock) 

PARAMETERS 

fLock - input 

TRUE—Increment the lock count of the object returned by this 
method. 

FALSE—Do not increment the lock count. 

RETURNS 

(nonzero value)—A pointer to the object this shadow points to. 

NULL—An error occurred or this shadow is currently not pointing to 
an object. 

HOWTO CALL 

This method can be called at any time on any WPShadow descendant 
to query its original object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpshadow.h 

NOTES 

Pass TRUE for the fLock parameter if you are going to access the object 
pointer after calling wpQueryShadowedObject. When the pointer is 
no longer needed, call wpUnlockObject. 


# wpSetLinkToObJect WPShadow instance method 

(Warp only) 

Sets the link between a shadow and another object. 

SYNTAX 

BOOL wpSetLinkToObject(WPObject * FromObject) 

PARAMETERS 

FromObject - input 

The pointer of the object to which this shadow is to be linked. 

RETURNS 

TRUE—The method completed successfully. 

FALSE —Ajq error occurred. 

HOWTO CALL 

This method can be called at any time. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpshadow.h 

SEE ALSO 

wpCreateShadowObject -50, wpCreateShadowObjectExt -296 

NOTES 

This method does not need to be called on a shadow created with 
wpCreateShadowObject or wpCreateShadowObjectExt. 
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• wpSetShadowTItSe WPStiadow instance method 

Sets the title of a shadow to be different from the title of the original 
object 

SYNTAX 

BOOL wpSetShadowTitle(PSZ pszNewTitle) 

PARAMETERS 

pszNewTitle - input 

A pointer to a string containing the new title for the shadow object. 
The system will make a copy of this string; therefore, it can be freed af¬ 
ter this call. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on any WPShadow descendant 
to set its title without modifying the title of the object to which it refers. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpshadow.h 

SEE ALSO 

wpQueryTitle -118, wpSetTitle -122 

RESTRICTIONS/WARNINGS 

m If wpSetTitle is called on a shadow object, it changes the title of the 
shadow as well as the original object, 
o There is no method to query the title of a shadow specifically. 

wpQueryTitle will return the title of the original object. 

9 If wpSetShadowTitle is called on a shadow object and wpSave- 
Deferred or wpSavelmmediate is also called, the title will revert back 
to that of the original object. 


T he Launch Pad is a new feature in Warp that enables the user to 
launch programs quickly and easily. When an object is added to 
the Launch Pad, a shadow of the object is created in the Nowhere 
folder and a button is displayed to represent that object. The default 
view of the object is opened when the user presses the button. Each 
item in the Launch Pad also has a drawer where more objects can be 
placed. 

The WPLaunch Pad class can be instantiated more than once and 
it can also be subclassed; therefore, many launch pads can exist in the 
system at once (the system will always open the Launch Pad with the 
object id of <WP_LAUNCHPAD>). It is also possible to enhance the 
main Launch Pad in the system by replacing the WPLaunch Pad class 
using WinReplaceObjectClass (pg. 19). To call methods on the default 
Launch Pad, call WinQueryObject on <WP_LAUNCHPAD> and then 
wpclsQueryObject to obtain the object pointer. 
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Restrictions and Warnings 

0 The methods described in this chapter can only be used by applica¬ 
tions developed for OS/2 Warp (version 3.0) or later versions. 


Instance Methods 


wpQueryActionButtons returns the list of action buttons displayed on 
the pad (pg. 303). 

wpQueryActionButtonStyle returns the style of the action buttons 
(pg. 304). 

wpQiieryCloseBrawer returns whether to close a drawer when a con¬ 
tained object is launched (pg. 305). 

wpQueryDisplaySmalllcons returns whether the buttons should dis¬ 
play small icons (pg. 305). 

wpQueryBisplayText returns whether to display text on the buttons in 
the main pad (pg. 306). 

wpQueryDisplayTextlnDrawers returns whether to display text on the 
buttons in the drawers (pg. 307). 

wpQueryDisplayVertical returns whether to display the pad vertically 
(pg. 308). 

wpQueryBrawerHWNB returns the window handle of a drawer 
(pg. 308). 

wpQueryFloatOnTop returns whether the pad should always be sur¬ 
faced to the top of the window z-order (pg. 309). 

wpQueryHideLaunchPadFrameCtls returns whether to hide the frame 
controls on the main pad (pg. 310). 

wpQueryObjectList returns the list of objects displayed in the main 
pad or a specific drawer (pg. 311). 

wpRefreshBrawer refreshes a drawer window or the main pad (pg. 312). 
wpSetActionButtonStyle sets the style of the action buttons (pg. 313). 
wpSetCloseBrawer sets whether to close a drawer when a contained 
object is launched (pg. 314). 

wpSetBisplaySmalllcons sets whether the buttons should display small 
icons (pg. 314) 

wpSetBisplayText sets whether to display text under the buttons in the 
main pad (pg. 315) 
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wpSetDisplayTextlnDrawers sets whether to display text under the but¬ 
tons in the drawers (pg. 316). 

wpSetDisplayVertical sets whether to display the pad vertically (pg. 317). 
wpSetDrawerHWND sets the window handle of a drawer (pg. 317). 
wpSetFloatOnTop sets whether the pad should always be surfaced to 
the top of the window z-order (pg. 318). 

wpSetHideLaunchPadFrameCtls sets whether to hide the frame con¬ 
trols on the main pad (pg. 319). 

wpSetObjectListFromHObjects inserts a list of objects into the pad 
using object handles (pg. 320). 

wpSetObjectListFromQbjects inserts a list of objects into the pad using 
object pointers (pg. 321). 

wpSetObjectListFromStrings inserts a list of objects into the pad using 
object IDs or file names (pg. 322). 


wpQueryActionButtons WPLaunchPad instance method 

Returns the list of action buttons displayed on the pad. 

SYNTAX 

PACTIONS wpQueryActionButtons (PULONG pulNumActions) 

PARAMETERS 

pulNumActions - output 

A pointer to the number of actions returned on this call. 

RETURNS 

A pointer to an array of ACTIONS (pg. 323) structures. pulNumActions 
contains the number of ACTIONS in the array. 

HOWTO CALL 

Call this method at any time to receive information describing the ac¬ 
tion buttons on the main pad. 

HOWTO OVERRIDE 

This method can be overridden to modify the returned actions. The 
parent method does not have to be called. 
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OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryActionButtonStyle -304, wpSetActionButtonStyle -313 


# wpQueryActionButtonStyle WPLaunch Pad 

Instance method 


Returns the style of the action buttons. 

SYNTAX 

ULONG wpQueryActionButtonStyle ( ) 

PARAMETERS 

none 

RETURNS 

The style for the action buttons on the main pad. One of the following 
values can be returned to specify how to display the buttons: 


Define 


Description 

ACTION_BUTT ON SJTEXT 

0 

Display the action buttons as text. 

ACTION_BUTTONS_OFF 

1 

Do not display the action buttons. 

ACTION_BUTT ON S_MINI 

2 

Display the action buttons with 
mini icons. 

ACTION JBUTTONSJMORMAL 

3 

Display the action buttons with 
normal-sized icons. 


HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSet¬ 
ActionButtonStyle should be used to change the style of the action 
buttons. 
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OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryActionButtons -303, wpSetActionButtonStyle -313 


® wpQueryCIoseDrawer WPLaunchPad instance method 

Returns whether to close a drawer when a contained object is launched. 

SYNTAX 

BOOL wpQueryCIoseDrawer ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Close drawers when their contents are launched. 

FALSE—Leave drawers opened. 

HOWTO CALL 

Call this method at any time. This behavior applies only to the drawers 
in a launch pad and not the main pad. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSetClose- 
Drawer should be used to change the behavior. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetCloseDrawer -314 


® wpQueryDisplaySmaSSIcons WPLaunch Pad 

instance method 


Returns whether the buttons should display small icons. 





306 


Workplace Shell 


SYNTAX 

BOOL wpQueryDisplaySmallIcons( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Display mini icons on the buttons. 

FALSE—Display normal-sized icons. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSetDis- 
playSmalllcons should be used to change this setting. 

OTHER SNFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetDisplaySmalllcons -314 


• wpQue ryDisplayText WPLaunchPad instance method 

Returns whether to display text on the buttons on the main pad. 

SYNTAX 

BOOL wpQueryDisplayText( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Display the object title text on the buttons on the main pad. 
FALSE—Do not display the text. 
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HOWTO CALL 

Call this method at any time. This setting applies only to the buttons 
on the main pad. Call wpOueryDisplayTextlnDrawers to query the set¬ 
ting for the drawers. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSetDis- 
playText should be used to change this setting. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpOueryDisplayTextlnDrawers -307, wpSetDisplayText -315, 
wpSetDisplayTextlnDrawers -316 


# wpQyeryDIspSayTextSriDrawers WPLauneh Pad 

instance method 


Returns whether to display text on the buttons in the drawers. 

SYNTAX 

BOOL wpOueryDisplayTextlnDrawers ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Display the object title text on the buttons in the drawers. 
FALSE—Do not display the text. 

HOWTO CALL 

Call this method at any time. This setting applies only to the buttons 
contained in drawers. Call wpQueryDisplayText to query the setting 
for the main pad. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSetDis¬ 
playTextlnDrawers should be used to change this setting. 
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OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryDisplayText -306, wpSetDisplayText -315, 
wpSetDisplayTextlnDrawers -316 


# wpQueryDispHayVertical WPLaunchPad instance method 

Returns whether to display the pad vertically. 

SYNTAX 

BOOL wpQueryDisplayVertical ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Display the pad vertically and the drawers horizontally. 

FALSE—Display the pad horizontally and the drawers vertically. This is 
the default. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, 
wpSetDisplayVertical should be used to change the behavior. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetDisplayVertical -317 


• wpQueryDrawerHWND WPLaunchPad instance method 


Returns the window handle of a drawer. 
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SYNTAX 

HWND wpOueryDrawerHWND(ULONG ulDrawer) 

PARAMETERS 

ulDrawer - input 

The number representing the drawer to query: 0 indicates the main 
pad; any other value indicates the index of the specific drawer; 1 is the 
first, 2 is the second, and so on. 

RETURNS 

(nonzero value)—The window handle of the main pad {ulDrawer is 0) 
or the window handle for a drawer {ulDrawer is greater than 0). 
NULLHANDLE—The view is not open {ulDrawer is 0) or the drawer is 
not open {ulDraweris greater than 0). 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, 
wpSetDrawerHWNB should be overridden for notification when a 
drawer is opened. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetDrawerHWNB -317 


® wpQueryFIoatOriTop WPLaunehPad instance method 

Returns whether the pad should always be surfaced to the top of the 
window z-order. 

SYNTAX 

BOOL wpOueryFloatOnTop( ) 

PARAMETERS 


none 
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RETURNS 

TRUE—Always surface the Launch Pad. 

FALSE—Allow the pad to be covered by other windows. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, 
wpSetFloatOnTop should be used to change the behavior. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetFloatOnTop -318 


® wpQueryHideLaunchPadFrameCtls WPLaunchPad 

instance method 


Returns whether to hide the frame controls on the main pad. 

SYNTAX 

BOOL wpQueryHideLaunchPadFrameCtls( ) 

PARAMETERS 

none 

RETURNS 

TRUE—Hide the system menu and title bar on the main pad. 

FALSE—Do not hide the frame controls. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification; however, wpSetHide- 
LaunchPadFrameCtls should be used to change this setting. 
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OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpSetHideLaunchPadFrameCtls -319 


® wpQueryObJectList WPLaunchPad instance method 

Returns the list of objects displayed in the main pad or a specific drawer. 

SYNTAX 

HOBJECT * wpQueryObjectList(ULONG ulDrawer, PULONG pul- 

NumObjects) 


PARAMETERS 

ulDrawer - input 

The number representing the drawer to query: 0 indicates the main 
pad; any other value indicates the index of the specific drawer; 1 is the 
first, 2 is the second, and so on. 
pulNumObjects - output 

A pointer to the number of object handles returned from this call. 

RETURNS 

A pointer to an array of object handles representing the objects con¬ 
tained in the main pad (ulDrawer is 0) or the drawer (ulDrawer is 
greater than 0). 

HOWTO CALL 

Call this method at any time. Call wpclsOueryObject to obtain an ob¬ 
ject pointer from an object handle. 

HOWTO OVERRIDE 

This method can be overridden; however, wpSetObjectListFromHOb- 
jects, wpSetObjectListFromObjects, or wpSetObjectListFromStrings 
should be used to change the contents of a launch pad. 

OTHER INFO 

Include files: wplnchpd.h 
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SEE ALSO 

wpclsQueryObject -75, wpSetObjectListFromHObjects -320, 
wpSetObjectListFromObjects -321, wpSetObjectListFromStrings -322 

NOTES 

The objects returned from this method are the shadow objects created 
by the Launch Pad, not the objects specified by the wpSetObject- 
ListFromXxx call. 


@ wp Ref res h D rawe r WPLatmchPad in stance method 


Refreshes a drawer window or the main pad. 

SYNTAX 

VOID wpRefreshDrawer(ULONG ulDrawer ) 

PARAMETERS 

ulDrawer - input 

The number representing the drawer to refresh: 0 indicates the main 
pad; any other value indicates the index of the specific drawer; 1 is the 
first, 2 is the second, and so on. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time to force the main pad or a drawer to be 
updated after changes have been made to its contents. While process¬ 
ing this method, the system will call wpSetDrawerHWND to set the 
handle to NULLHANDLE while refreshing, and then call wpSet¬ 
DrawerHWND to reset the handle. 

HOWTO OVERRIDE 

This method can be overridden for notification when the main pad or 
a drawer is being refreshed. 


OTHER INFO 

Include files: wplnchpd.h 
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SEE ALSO 

wpSetDrawerHWND -317 


• wpSetActlonBottoriStySe WPLaundhPad 

instance method 


Sets the style of the action buttons. 

SYNTAX 

BOOL wpSetActionButtonStyle(ULONG ulStyle) 

PARAMETERS 

ulStyle - input 

The style for the action buttons on the main pad. One of the following 
values can be used to specify how to display the buttons: 

Define Description 


ACTION_BUTTONS_TEXT 

0 

Display the action buttons as text. 

ACTION_BUTTONS_OFF 

1 

Do not display the action buttons. 

ACTION_BUTTONS_MINI 

2 

Display the action buttons with 
mini icons. 

ACTION JBUTTONS_NORMAL 

3 

Display the action buttons with 
normal-sized icons. 


RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when the action but¬ 
ton style has been changed. 


OTHER INFO 

Include files: wplnchpd.h 
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SEE ALSO 

wpQueryActionButtons -303, wpQueryActionButtonStyle -304 


# wpSetCloseDrawer WPLaundiPad instance method 

Sets whether to close a drawer when a contained object is launched. 

SYNTAX 

VOID wpSetCloseDrawer (BOOL fState) 

PARAMETERS 

fState - input 

TRUE—Close drawers when their contents are launched. 

FALSE—Leave drawers opened. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. This behavior applies only to the drawers 
in a launch pad and not the main pad. 

HOWTO OVERRIDE 

This method can be overridden for notification when this behavior is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryCloseDrawer -305 


# wpSetDisplaySmaSIlcons WPLaunchPad instance method 


Sets whether the buttons should display small icons. 

SYNTAX 

VOID wpSetDisplaySmall!cons(BOOL fState) 
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PARAMETERS 

/State - input 

TRUE—Display mini icons on the buttons. 

FALSE—Display normal-sized icons. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when this setting is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryDisplaySmalllcons -305 


• wpSetDSspiayText WPLaunehPad instance method 

Sets whether to display text on the buttons on the main pad. 

SYNTAX 

VOID wpSetDisplayText(BOOL /State) 

PARAMETERS 

/State - input 

TRUE—Display the object title text on the buttons on the main pad. 
FALSE—Do not display the text. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. This setting applies only to the buttons 
on the main pad. Call wpSetDisplayTextlnDrawers to change the set¬ 
ting for the drawers. 
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HOWTO OVERRIDE 

This method can be overridden for notification when this setting is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryDisplayText -306, wpQueryDisplayTextlnDrawers -307, 
wpSetDisplayTextlnBrawers -316 


® wpSetDisplayTextlnDrawers WPLaurschPad Instance 

method 


Sets whether to display text on the buttons in the drawers. 

SYNTAX 

VOID wpSetDisplayTextlnDrawers (BOOL /State) 

PARAMETERS 

/State - input 

TRUE—Display the object title text on the buttons contained in the 
drawers. 

FALSE—Do not display the text. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. This setting applies only to the buttons 
contained in drawers. Call wpSetDisplayText to set the setting for the 
main pad. 

HOWTO OVERRIDE 

This method can be overridden for notification when this setting is 
changed. 


OTHER SNFO 

Include files: wplnchpd.h 
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SEE ALSO 

wpQueryDisplayText -306, wpQueryDisplayTextlnDrawers -307, 
wpSetDisplayText -315 


• wpSetDispiayVertical WPLaunchPad instance method 

Sets whether to display the pad vertically. 

SYNTAX 

VOID wpSetDispiayVertical (BOOL fState) 

PARAMETERS 

fState - input 

TRUE—Display the pad vertically and the drawers horizontally. 

FALSE—Display the pad horizontally and the drawers vertically. This is 
the default. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when this behavior is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryDisplayVertical -308 


# wpSetPrawerHWND WPLaunchPad Instance method 


Sets the window handle of a drawer. 
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SYNTAX 

VOID wpSetDrawerHWND (ULONG ulDrawer, HWND hwnd) 
PARAMETERS 

ulDrawer - input 

The number representing the drawer to query: 0 indicates the main 
pad; any other value indicates the index of the specific drawer; 1 is the 
first, 2 is the second, and so on. 
humd - input 

The window handle of the main pad (ulDrawer is 0) or the window han¬ 
dle for the drawer (ulDrawer is, greater than 0). 

RETURNS 

none 

HOWTO CALL 

This method is generally called by the system. 

HOWTO OVERRIDE 

This method can be overridden for notification when a drawer is opened. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryDrawerHWND -308 


# wpSetFloatOn Top WPLaunchPad Instance method 

Sets whether the pad should always be surfaced to the top of the win¬ 
dow z-order. 

SYNTAX 

VOID wpSetFloatOnTop (BOOL fState) 

PARAMETERS 

fState - input 

TRUE— Always surface the Launch Pad. 

FALSE—Allow the pad to be covered by other windows. 
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RETURNS 

none 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when the behavior is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryFloatOnTop -309 

NOTES 

If more than one launch pad is set with the float-on-top behavior, the 
result will be unpredictable. 


# wpSetHideLaunch PadFrameCtls WPLaunchPad 

Instance method 


Sets whether to hide the frame controls on the main pad. 

SYNTAX 

VOID wpSetHideLaunchPadFrameCds (BOOL /State) 

PARAMETERS 

/State - input 

TRUE—Hide the system menu and title bar on the main pad. 
FALSE—Do not hide the frame controls. 

RETURNS 

none 

HOWTO CALL 

Call this method at any time. 
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HOWTO OVERRIDE 

This method can be overridden for notification when this setting is 
changed. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryHideLaunchPadFrameCtls -310 


® wpSetObjectList FromHObJects WPLaunchPad 

instance method 


Inserts a list of objects into the pad using object handles. 

SYNTAX 

BOOL wpSetObjectListFromHObjects(ULONG ulDrawer , ULONG 

ulNumObjects, HOBJECT *phob- 
jects, ULONG ulAfter) 


PARAMETERS 

ulDrawer - input 

The number representing the drawer to set: 0 indicates the main pad; 
any other value indicates the index of the specific drawer; 1 is the first, 
2 is the second, and so on. 
ulNumObjects - output 

A pointer to the number of object handles in phobjects. 
phohjects - input 

A pointer to an array of object handles that represents the objects to be 
inserted into the pad. 
ulAfter - input 

The place after which to place the objects. Set this to ADD_- 
OBJECTS_FIRST to place them at the front, ADD_OBJECTS_LAST to 
place them at the end, or a number greater than 0 specifying the index 
of the object after which to place the objects. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when objects are 
added to the Launch Pad. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryObjectList -311, wpSetObjectListFromObjects -321, 
wpSetObjectListFromStrings -322 


# wpSetObJectLJst FromObjects WPLaundhPad 

Instance method 


Inserts a list of objects into the pad using object pointers. 

SYNTAX 

BOOL wpSetObjectListFromObjects (ULONG ulDrawer, ULONG 

ulNumObjects, WPObject ** objects, 
ULONG ulAfter) 


PARAMETERS 

ulDrawer - input 

The number representing the drawer to set: 0 indicates the main pad; 
any other value indicates the index of the specific drawer; 1 is the first, 
2 is the second, and so on. 
ulNumObjects - output 

A pointer to the number of object pointers in objects, 
objects - input 

A pointer to an array of object pointers to be inserted into the pad. 
ulAfter - input 

The place after which to place the objects. Set this to ADB_OB- 
JECTSJFIRST to place them at the front, ADD_OBJECTS_LAST to 
place them at the end, or a number greater than 0 specifying the index 
of the object after which to place the objects. 
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RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when objects are 
added to the Launch Pad. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpQueryObjectList -311, wpSetObjectListFromHObjects -320, 
wpSetObjectListFromStrings -322 


# wpSetObjectListFromStrings WPLaunehPad 

instance method 


Inserts a list of objects into the pad using object IDs or file names. 


SYNTAX 

BOOL wpSetObjectListFromStrings (ULONG uIDrawer, PSZ pszSetup , 

ULONG ulAfter) 


PARAMETERS 

uIDrawer- input 

The number representing the drawer to set: 0 indicates the main pad; 
any other value indicates the index of the specific drawer; 1 is the first, 
2 is the second, and so on. 
pszSetup - input 

A super string containing object IDs and/or fully qualified paths of ob¬ 
jects to insert. Each item is separated by a AO’ character and the entire 
string is terminated with two AO’ characters. 
ulAfter - input 

The place after which to place the objects. Set this to ADD_OR- 
JECTS_FIRST to place them at the front, ADD_OBJECTS_LAST to 
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place them at the end, or a number greater than 0 specifying the index 
of the object after which to place the objects. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method can be overridden for notification when objects are 
added to the Launch Pad. 

OTHER INFO 

Include files: wplnchpd.h 

SEE ALSO 

wpOueryObjectList -311, wpSetObjectListFromHObjects -320, 
wpSetObjectListFromObjects -321 


Launch Pad Objects: Structures 


ACTIONS _ 



pszTitle (PSZ) 0 

The title for the action button. 

ulMenuId (ULONG) 4 

The menu ID for this action. When an action button is pressed, the menu ID is sent to the 
desktop via wpMenuItemSelected. This should be a valid desktop menu ID (defined in 
wpobject.h). If this is set to something other than a valid desktop menu ID, the WPDesktop 
class must be replaced to handle the new value in the wpMenuItemSelected override. 
Choose from the following list of desktop menu IDs: 
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Define Menu item 


WPMENUID_FIND 

8 

Find 

WPMENUID_TREE 

123 

Tree view 

WPMENUIDJCON 

303 

Icon view 

WPMENUID_DETAILS 

304 

Details view 

WPMENUID_SHUTDOWN 

704 

Shutdown 

WPMENUID_LOCKUP 

705 

Lockup 

WPMENUID_SYSTEMSETUP 

713 

System setup 


Used by: wpQueryActionButtons -303 





A palette is an object that presents a selection of cells that can be 
dropped on a window to perform an action. For example, the 
palette view of the Color Palette shows a grid of color circles that can 
be edited or dropped on a window to change its color. 

A subclass of WPPalette can be written to create user-defined 
palettes. The WPPalette class provides a palette window with empty 
cells, while the subclass paints the cells and provides the edit dialog 
and drag behavior. Each cell can be assigned user-defined data; 
WPPalette saves this cell data in wpSaveState. 
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Restrictions and Warnings 

• There is no method to set the help panel to display when help is re¬ 
quested from a palette window. wpQueryPaletteHelp returns only a 
help panel ID which will be used with the default Workplace help li¬ 
brary; therefore other libraries cannot be specified. To provide help, 
override wpOpen and subclass the client window created by the par¬ 
ent class (the client can be obtained by calling WinWindowFromID 
on the frame using the FID_CLIENT ID). From the subclass window 
procedure, process the WM_HELP message. 
m There is no method for changing the instruction text of a palette 
window. 


fnstonce Methods 


wpDragCell notifies a palette that the user has started to drag a cell 
(pg- 327). 

wpEditCell notifies a palette that the user has requested to edit a cell 
(pg. 328). 

wpPaintCell paints a cell in a palette (pg. 329). 

wpRedrawCell notifies a palette that a cell needs to be redrawn 
(pg- 330). 

wpQueryPalettelnfo returns information about a palette object 
(pg. 330). 

wpSelectCell (Warp) selects a cell in a palette view (pg. 331). 
wpSetPalettelnfo sets information about a palette object (pg. 332). 
wpSetupCell sets the class specific data on a cell of a palette object 
(pg- 333). 
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• wpDragCell WPPalette instance method 

Notifies a palette that the user has started to drag a cell. 

SYNTAX 

BOOL wpDragCell (PCELL pCell, HWND hwndPal, PPOINTL ptlDrag) 

PARAMETERS 

pCell - input 

A pointer to the CELL (pg. 335) structure of the cell under the cursor 
when the user began the drag. 
hwndPal - input 

The window handle for the open palette window. 
ptlDrag - input 

A pointer to a POINTL (pg. 137) structure which contains the coordi¬ 
nates of the mouse pointer when the drag began. These coordinates 
are in relation to the palette window. 

RETURNS 

TRUE —The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when the palette 
window receives the WM_BEGINDRAG message. 

HOWTO OVERRIDE 

Override this method to provide the drag functionality for a WPPalette 
subclass. WPPalette subclasses do not use the PM Drag facility but in¬ 
stead capture the mouse pointer. In this override, capture the mouse 
and use an invisible window to process the messages. When the window 
receives the WM_BUTTON2UP message, perform the action defined 
by this palette subclass on the window under the mouse pointer and 
stop capturing the mouse. The parent method takes no action and re¬ 
turns FALSE. 

OTHER INFO 

Include files: wppalet.h and os2def.h 
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SEE ALSO 

wpEditCell -328, wpPaintCell -329, wpRedrawCell -330, 
wpSetupCell -333 


# wpEditCell WPPalette instance method 

Notifies a palette that the user has requested to edit a cell. 

SYNTAX 

BOOL wpEditCell (PCELL pCell, HWND hwndPal) 

PARAMETERS 

pCell - input 

A pointer to the CELL (pg. 335) structure of the cell to edit. 
hwndPal - input 

The window handle for the open palette window. 

RETURNS 

TRUE—The method completed successfully. 

FALSE-—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when the user dou¬ 
ble-clicks on a cell or selects the edit button. 

HOWTO OVERRIDE 

Override this method to provide the interface for the user to edit the 
cell. The parent method takes no action and returns FALSE. 

OTHER INFO 

Include files: wppalet.h and os2def.h 

SEE ALSO 

wpDragCell -327, wpPaintCell -329, wpRedrawCell -330, 
wpSetupCell -333 
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# wpPaintCell WPPalette Instance method 


Paints a cell in a palette. 

SYNTAX 

BOOL wpPaintCell (PCELL pCell, HPS hps , PRECTL prcl, BOOL 
fHilite) 


PARAMETERS 

pCell - input 

A pointer to the CELL (pg. 335) structure of the cell that must be 

painted. 

hps - input 

The presentation space handle for the palette window. 
prcl - input 

A pointer to a RECTL structure (pg. 336) that contains the coordi¬ 
nates for the cell. 
fHilite - input 

TRUE—The cell is currently selected. 

FALSE—This cell is not currently selected. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when a cell must be 
painted in response to a WM_PAINT message or the wpRedrawCell 
method. 

HOWTO OVERRIDE 

Override this method to paint the cells of the palette. The parent 
method will fill the cell with SYSCLR_WINDOW if fHilite is FALSE or 
SYSCLR_HIGHLITEBACKGROUND if fHilite is TRUE. If the parent 
method is called, it should be called first. 

OTHER INFO 

Include files: wppaleth and os2def.h 

SEE ALSO 

wpDragCell -327, wpEditCell -328, wpRedrawCell -330, 
wpSet upCell -333 _ 
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• wpRedrawCelf WPPalette instance method 


Notifies a palette that a cell needs to be redrawn. 

SYNTAX 

BOOL wpRedrawCell (PCELL pCell) 

PARAMETERS 

pCell - input 

A pointer to the CELL (pg. 335) structure of the cell to redraw. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to invalidate the region of a cell 
to force it to redraw. This will cause the wpPaintCell method to be 
called. 

HOWTO OVERRIDE 

This method is generally not overridden. Override wpPaintCell to ac¬ 
tually paint the cell. 

OTHER INFO 

Include files: wppalet.h 

SEE ALSO 

wpDragCell -327, wpEditCell -328, wpPaintCell -329, wpSetupCell -333 


% wpQueryPalettelnfo WPPalette instance method 

Returns information about a palette object. 

SYNTAX 

BOOL wpQueryPalettelnfo (PPALINFO pPallnfo) 

PARAMETERS 

pPallnfo - input/output 
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A pointer to a PALINFO structure (pg. 335) which, upon return, will 
be filled with information about this palette object. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method any time to retrieve information about a palette ob¬ 
ject. This is useful in determining the number of cells to set up with 
wpSetupCell. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wppalet.h 

SEE ALSO 

wpSetPalettelnfo -332, wpSetupCell -333 


® wpSelectCell WPPalette instance method (Warp only) 

Selects a cell in a palette view. 

SYNTAX 

VOID wpSelectCell (HWND hwndPal, PCELL pCell) 

PARAMETERS 

hwndPal - input 

The window handle of the Palette view. 
pCell - input 

A pointer to the CELL (pg. 335) structure of the cell to select. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method can be called at any time but is generally called by the sys¬ 
tem when the user selects a cell. 

HOWTO OVERRIDE 

Override this method for notification when a cell has been selected. 
wpPaintCell will also be called to redraw the cell. 

OTHER INFO 

Include files: wppalet.h 

SEE ALSO 

wpPaintCell -329, wpSetupCell -333 


• wpSetPalettelnfo WPPalette instance method 

Sets information about a palette object. 

SYNTAX 

BOOL wpSetPalettelnfo (PPALINFO pPallnfo) 

PARAMETERS 

pPallnfo - input/output 

A pointer to a PALINFO structure (pg. 335) filled with information 
about this palette object. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set information about a palette object. 
The wpQueryPalettelnfo method should be called first to retrieve the 
current settings of the palette. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wppalet.h 

SEE ALSO 

wpQueryPalettelnfo -330, wpSetupCell -333 

NOTES 

The xCursor and yCursor fields in the PALINFO structure cannot be 
changed. 


• wpSetupCell WPPalette instance method 

Sets the class-specific data on a cell of a palette object. 

SYNTAX 

BOOL wpSetupCell (PVOED pCelLData, ULONG cb, ULONG x, 
ULONG y) 


PARAMETERS 

pCellData - input 

A pointer to the class-specific data to assign to this cell. 
cb - input 

The size of the pCellData buffer. 
x- input 

The column number of this cell. 
y - input 

The row number of this cell. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method when the object is initialized on each cell to add the 
class-specific data. Call wpQueryPalettelnfo to determine the number 
of rows and columns in this palette. A copy of the data will be made for 
the cell; therefore, it can be freed after this call. 


HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wppalet.h 

SEE ALSO 

wpOueryPalettelnfo -330, wpSetup -63, wpSetupOnce -64 

RESTRICTIONS/WARNINGS 

$ Call wpSetupCell only after the palette has been completely initial¬ 
ized. For OS/2 version 2.1, Override wpSetup to set up the cells but 
ensure wpSetup is being called on a new object and not from 
WinSetObjectData. For OS/2 Warp or later, set up the cells from the 
wpSetupOnce override. 


Class Methods 


wpclsQueryEditString returns the string used for the edit pushbutton 
in the palette view (pg. 334). 


• wpclsQueryEditString WPPaSette class method 

Returns the string used for the edit pushbutton in the palette view. 

SYNTAX 

PSZ wpclsQueryEditString ( ) 

PARAMETERS 

none 

RETURNS 

(nonzero value)—-A pointer to the edit string for this class. 

NULL—This class does not have an edit string defined. 

HOWTO CALL 

Call this method at any time to query the edit string for the class. 
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HOWTO OVERRIDE 

Override this method to return the edit string for the class. The system 
will automatically resize the edit button to fit the length of the string. 
This string will be accessed by the system each time a palette window is 
opened so the memory for the string must be valid for as long as the 
class is loaded. A global variable can be used for this purpose. 

OTHER INFO 

Include files: wppalet.h 


Palette Objects: Structures 

CELL (4 bytes + class-specific data) 

cbData (ULONG) 0 

The size of the cell data. 

Note: The CELL structure is immediately followed by class-specific data. 

Used by: wpDragCell -327, wpEditCell -328, wpPaintCell -329, wpRedrawCell -330, 
wpSelectCeli -331 



xCell Count (ULONG) 

The number of columns of cells. 


yCellCount (ULONG) 

The number of rows of cells. 

xCursor (ULONG) 

The x position of the cursor. This value cannot be changed. 
yCursor (ULONG) 

The y position of the cursor. This value cannot be changed. 

xCellWidth (ULONG) 

The width of each cell in pixels. 

yCellHeight (ULONG) 

The height of each cell in pixels. 
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xGap (ULONG) 

The gap, in pixels, between each column of cells. 

24 

yGap (ULONG) 

The gap, in pixels, between each row of cells. 

28 


Used by: wpQueryPalettelnfo -330, wpSetPalettelnfo -332 



xLeft (ULONG) 0 

The x coordinate for the lower left point of the rectangle. 

yBottom (ULONG) 4 

The y coordinate for the lower left point of the rectangle. 

xRigfat (ULONG) 8 

The x coordinate for the upper right point of the rectangle. 

yTop (ULONG) 12 

The y coordinate for the upper right point of the rectangle. 

Used by: wpPaintCell -329 




W; 


orkplace Shell provides help primarily by creating a global help 
instance for all objects. Application help files are appended 


when wpDisplayHelp is called. This help instance is used to provide 
general object help, help for pop-up menu items, or to display individ¬ 
ual help panels at any time. 

Settings notebooks each have their own help instances which are 
created just after all classes have inserted their pages. The PAGEINFO 
structure passed to wpInsertSettingsPage contains fields for the gen¬ 
eral help panel, help library, and help table for each page. 
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Restrictions and Warnings 

% After calling wpDisplayHelp, the application’s help library is in¬ 
cluded in the Workplace help instance and, therefore, will be in use. 
If you need to delete or replace this file, press FI when an object 
from another class is selected and your library file will be unloaded. 


Instance Methods 


wpDisplayHelp displays a help panel from the specified help library 
(pg. 338). 

wpMenuItemHelpSelected notifies an object that the user summoned 
help for a pop-up menu item (pg. 339). 

wpQueryDefaultHelp returns the general help panel for an object 
(pg. 340). 

wpSetDefaultHelp sets the general help panel for an object (pg. 341). 


@ wpPispgayHegp WPObject instance method 


Displays a help panel from the specified help library. 

SYNTAX 

BOOL wpDisplayHelp (ULONG HelpPanelld, PSZ HelpLibrary) 

PARAMETERS 

HelpPanelld - input 

The resource ID for the help panel to display. 

HelpLibrary - input 

A pointer to a string containing the name of the help file where 
HelpPanelld is contained. The file name does not need to be fully qual¬ 
ified if the help file is in the HELP path specified in CONFIG.SYS. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method can be called at any time to display a help panel for an ob¬ 
ject. Use this method to display the help panels for menu items in the 
wpMenuItemHelpSelected override. The system will call this method 
using the values returned from wpQueryDefaultHelp to display gen¬ 
eral help for an object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobjecth 

SEE ALSO 

wpclsQueryDefaultHelp -342, wpMenuItemHelpSelected -339, 
wpQueryDefaultHelp -340, wpSetDefaultHelp -341 


• wpMenuStemHeipSelected WPObject Instance method 


Notifies an object that the user summoned help for a pop-up menu 
item. 

SYNTAX 

BOOL wpMenuItemHelpSelected (ULONG Menuld) 

PARAMETERS 

Menuld - input 

The ID of the menu item for which help was requested. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system when the user 
pressed FI while a pop-up menu item has the focus. 

HOWTO OVERRIDE 

Override this method to provide help for menu items added by your 
class. If Menuld is not one of your menu items, call the parent method. 
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Otherwise, call wpDisplayHelp to display the help panel. (See sample 
below.) 


OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsOueryDefaultHelp -342, wpDisplayHelp -338, 
wpQueryDefaultHelp -340, wpSetDefaultHelp -341 


SAMPLE CODE 

This sample demonstrates how to override wpMenuItemHelpSelected. 
The following is from the .h file: 


#define IDM_MYMENUITEM WPMENUID_USER 
#define RES_MYMENUITEM 1000 


The following is from the .c file: 


SOM_Scope BOOL SOMLINK mcls_wpMenuItemHelpSelected(MyClass *somSelf / 

ULONG Menuld) 


/* Check if the menu id is one added by this class. */ 
if (Menuld =- IDM_MYMENUITEM) 

return (_wpDisplayHelp(somSelf, RES_MYMENUITEM, 

"MYCLASS.HLP")); 

else 

return (parent_wpMenu!temHelpSelected(somSelf,Menuld)); 


# wpQueryDefaultHelp WPObJect instance method 

Returns the general help panel for an object. 

SYNTAX 

BOOL wpQueryDefaultHelp (PULONG pHelpPanelld , PSZ HelpLibrary) 

PARAMETERS 

pHelpPanelld - output 

A pointer to a ULONG which, upon return, will contain the resource 
ID of the general help panel for this object. 
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HelpLihrary - input/output 

A pointer to a string buffer which, upon return, will contain the help 
library name for this object. This buffer must be at least the size of 
CCHMAXPATH. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to determine the general help panel and 
library for an object. Pass pHelpPanelld and HelpLibrary to wpDisplay- 
Help to display the help panel. By default, the object will return the 
values returned from wpclsQueryDefaultHelp. 

HOWTO OVERRIDE 

This method is generally not overridden. Call wpSetDefaultHelp to 
change the default help panel for an object. 

OTHER INFO 

Include files: wpobject.h and bsedos.h 

SEE ALSO 

wpclsQueryDefaultHelp -342, wpDisplayHelp -338, 
wpSetDefaultHelp -341 


® wpSetDefaultHelp WPObJect instance method 

Sets the general help panel for an object. 

SYNTAX 

BOOL wpSetDefaultHelp (ULONG HelpPanelld, PSZ HelpLibrary) 

PARAMETERS 

HelpPanelld - input 

The resource ID of the general help panel for this object. 

HelpLibrary - input 

A pointer to a string containing the help library name for this object. 
The size of this string must be less than or equal to CCHMAXPATH. If 
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the help file is in the HELP path in CONFIG.SYS, HelpLibrary does not 
need to be fully qualified. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the general help panel and library 
for an object. By default, the object will use the values returned from 
the wpclsQueryBefaultHelp override. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h and bsedos.h 

SEE ALSO 

wpclsQueryBefaultHelp -342, wpBisplayHelp -338, 
wpQueryBefaultHelp -340 


Class Methods 


wpclsQueryBefaultHelp returns the general help panel for a class 
(pg- 342). 


© wpcisQueryDefaultHelp WPObJect class method 

Returns the default help panel for a class. 

SYNTAX 

BOOL wpcisQueryDefaultHelp (PULONG pHelpPanelld, PSZ 

HelpLibrary) 
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PARAMETERS 

pHelpPanelld - output 

A pointer to a ULONG which, upon return, will contain the resource 
ID of the general help panel for this object. 

HelpLibrary - input/output 

A pointer to a string buffer which, upon return, will contain the help 
library name for this object. This buffer must be at least the size of 
CCHMAXPATH. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to determine the class default general 
help panel. 

HOWTO OVERRIDE 

Override this method to return the general help panel for this class. 
All instances will use this panel as their general help unless 
wpSetDefaultHelp is called. When the system calls this method, the 
size of the HelpLibrary buffer is CCHMAXPATH. 

OTHER INFO 

Include files: wpobject.h and bsedos.h 

SEE ALSO 

wpDisplayHelp -338, wpQueryDefaultHelp -340, wpSetDefaultHelp -341 





The Printer Object 

When a print queue is created in the system, the system creates a 
printer object on the desktop to represent the queue. Printer objects 
are descendants of WPPrinter and provide the user interface for the 
print subsystem. Users can change settings on the print queues using 
the settings notebook, and can print objects by dragging and dropping 
them on the printer objects. 

Printing Workplace Objects 

Any Workplace class can specify print behavior for its objects. For an 
object to be printable, its style must not contain OBJSTYLE_NO- 
PRINT. An entire class of objects can be defined as printable by re¬ 
moving the CLSSTYLE_NEVERPRINT flag from the class default style. 

When the user selects Print from the pop-up menu or drags the 
object to the printer, the wpPrintObject method is called. It is then up 
to the object to print the data. The only default Workplace class that 
handles the wpPrintObject method is WPDataFile. A WPDataFile sub¬ 
class can change the print behavior by overriding one of the 
WPPrintXxxFile methods. 
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Restrictions and Warnings 

• Print objects can only be created by the SplXxx APIs in OS/2 ver¬ 
sions before Warp. 


instance Methods 


wpDeleteAllJobs deletes all the jobs in a printer (pg. 346). 
wpHoldPrinter holds the queue of a printer (pg. 346). 
wpJobAdded (Warp) notifies a printer that a job has been added to the 
queue (pg. 347). 

wpJobChanged (Warp) notifies a printer that a job in the queue has 
been changed (pg. 348). 

wpJobBeleted (Warp) notifies a printer that a job has been removed 
from the queue (pg. 348). 

wpPrintMetaFile prints a file in metafile format (pg. 349). 
wpPrlntObject notifies an object that a print request has been made by 
the user (pg. 350). 

wpPrintPifFile prints a file in PIF format (pg. 358). 
wpPrintPlalnTextFile prints a file in plain text format (pg. 359). 
wpPrintPrinterSpecificFile prints a file in printer-specific format 
(pg. 360). 

wpPrintUeknownFile prompts the user for the format of a file and 
then calls the appropriate print method (pg. 361). 
wpReleasePrinter releases the queue of a printer (pg. 362). 
wpQueryComputerName returns the computer name of a printer 
(pg- 363). 

wpQueryPrinterName returns the printer name for a printer 
(Pg- 363). 

wp Query Queue Options (Warp) returns the queue options of a printer 
(pg- 364). 

wpQueryRemoteOptions (Warp) returns the remote options of a 
printer (pg. 365). 

wpSetBefaultPrinter sets a printer object as the default printer 
(pg- 366). 

wpSetQueueOptions (Warp) sets the queue options of a printer 
(pg- 367). 

wpSetRemoteOptions (Warp) sets the remote options of a printer 
(pg. 368). 
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# wpDeleteASSJobs WPPrinter instance method 

Deletes all the jobs in a printer object. 

SYNTAX 

BOOL wpDeleteAHJobs( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to delete the pending jobs from 
the queue of a printer object. The user must be logged on as a network 
administrator for this method to have an effect on a network printer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpHoldPrinter -346, wpRe lease Printer -362 


® wpHoldPrinter WPPrinter Instance method 

Holds the queue of a printer object. 

SYNTAX 

BOOL wpHoldPrinter ( ) 

PARAMETERS 


none 
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RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on a printer object to hold the 
queue. The user must be logged on as a network administrator for this 
method to have an effect on a network printer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpBeleteAllJobs -346, wpReleasePrinter -362 


• wpjobAdded WPPrinter instance method (Warp only) 

Notifies a printer that a job has been added to the queue. 

SYNTAX 

BOOL wpjobAdded (ULONG uljobld) 

PARAMETERS 

uljobld - input 

The ID of the job added to the queue. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system. 

HOWTO OVERRIDE 

Override this method for notification when a job is added to the print 
queue. You must call the parent method. 
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OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpJobChanged -348, wpjobDeleted -348 


• wpJobChanged WPPrinter Instance method (Warp only) 

Notifies a printer that a job in the queue has been changed. 

SYNTAX 

BOOL wpJobChanged(ULONG uljobld, ULONG ulReserved) 

PARAMETERS 

uljobld - input 

The ID of the job that has changed. 
ulReserved - reserved 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system. 

HOWTO OVERRIDE 

Override this method for notification when a job in the print queue 
has changed. You must call the parent method. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpJobAdded -347, wpjobDeleted -348 


• wpjobDeleted WPPrinter instance method (Warp only) 


Notifies a printer that a job has been removed from the queue. 
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SYNTAX 

BOOL wpJobDeleted(ULONG uljobld) 

PARAMETERS 

uljobld - input 

The ID of the job removed from the queue. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method is generally only called by the system. 

HOWTO OVERRIDE 

Override this method for notification when a job is removed from the 
print queue. You must call the parent method. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpJobAdded -347, wpJobChanged -348 


• wpPrintMetaPile WPDataFile instance method 


Prints a file in metafile format. 

SYNTAX 

BOOL wpPrintMetaFile (PPRINTDEST pPrintDest) 

PARAMETERS 

pPrintDest - input 

A pointer to a PRINTDEST structure (pg. 369) containing the infor¬ 
mation needed to open the device context for the desired printer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method can be called at any time to print a data file object in 
metafile format. The WPDataFile class handles this method by invoking 
a function in the Picture Viewer (PICVTEW.EXE) to print the metafile. 

HOWTO OVERRIDE 

This method can be overridden to replace the print behavior of 
metafiles. When the user requests to print a metafile, the system will in¬ 
voke wpPrintObject on the file. The WPDataFile class will respond by 
calling this method. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpPrintObject -350, wpPrintPifFile -358, wpPrintPlainTextFile -359, 
wpPrintPrinterSpecificFile -360, wpPrintUnknownFile -361 


® wpPrintObject WPObje ct instance method 

Notifies an object that a print request has been made by the user. 

SYNTAX 

BOOL wpPrintObject(PPRINTDEST pPrintDest, ULONG ulReserved) 

PARAMETERS 

pPrintDest - input 

A pointer to a PRINTDEST structure (pg. 369) containing the infor¬ 
mation needed to open the device context for the desired printer. 
ulReserved - reserved 
Set this parameter to 0. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred or printing is not supported. 

HOWTO CALL 

This method can be called at any time to print an object that supports 
printing. To determine if an object can be printed, call wpQueryStyle 
and check that the OB}STYLE_NOPRINT flag is not returned. 
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HOWTO OVERRIDE 

This method can be overridden to provide printing for an object. If you 
are replacing the print functionality of the object or the parent class 
does not support printing, do not call the parent method. WPDataFile 
is the only predefined Workplace class that supports printing. 

The system will call this method from the user interface thread of 
Workplace Shell. wpPrintObject processing should be done on a sepa¬ 
rate thread to enable the user to continue to interact with the system 
while the object is printing. Be sure to make a copy of the pPrintDest pa¬ 
rameter to pass to the thread (see sample below). 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpPrintMetaFile -349, wpPrintPifFile -358, wpPrintPlainTextFile -359, 
wpPrintPrinterSpecificFile -360, wpPrintUnknownFile -361 

SAMPLE CODE 

This sample demonstrates how to provide printing for a WPFolder sub¬ 
class. When wpPrintObject is called, a separate thread will print the 
contents of the folder. It is beyond the scope of this book to delve into 
the details of PM printing, therefore, the PrintFolder function is a 
crude example that does not support font selection or other important 
aspects of printing. 

The following is from the .h file: 

/* structure for the thread parameter */ 
typedef struct _THREADDATA 
{ 

WPFolder *Folder; 

PPRINTDEST pPrintDest; 

} THREADDATA, *PTHREADDATA; 

VOID PrintFolder(PTHREADDATA pData); 

PPRINTDEST CreateDupPrintDest(PPRINTDEST pPrintDest); 

VOID FreePrintDest(PPRINTDEST pPrintDest); 

The following is from the .c file: 

/* Override wpPrintObject to print the folder */ 

SOM_Scope BOOL SOMLINK mfdr_wpPrintObject(MyFolder *somSelf, 

PPRINTDEST pPrintDest, 

___ULONG ulReserved)__ 
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{ 

PPRINTDEST pDupPrintDest; 

PTHREADDATA pData; 

TID tid; 

/* Make a copy of the PRINTDEST structure so the thread can use it 
after this method returns. 

*/ 

pDupPrintDest = CreateDupPrintDest(pPrintDest); 
if (pDupPrintDest) 

{ 

pData = malloc(sizeof(THREADDATA)); /* Create the thread 

parameter */ 

if (pData) 

{ 

pData->Folder = somSelf; 
pData->pPrintDest = pDupPrintDest; 

/* Lock this folder so it doesn't go to sleep while 
printing */ 

_wpLockObject(somSelf)/ 

if (DosCreateThread(&tid, (PFNTHREAD) PrintFolder, 

(ULONG) pData, 

0, 0x10000)) 

{ 

free(pData); 

FreePrintDest(pDupPrintDest); 

_wpUnlockObject(somSelf); 

} 

else 

return(TRUE); 

} /* endif pData */ 
else 

FreePrintDest(pDupPrintDest); 

} 

return (FALSE); 

} 

#undef SOM_CurrentClass 
#define SOM_CurrentClass SOMMeta 

/* Override wpclsQueryStyle to remove the CLSSTYLE_NEVERPRINT flag */ 
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SOM_Scope ULONG SOMLINK mfdrM_wpclsQueryStyle(M_MyFolder *somSelf) 

{ 

return (parent_wpclsQueryStyle(somSelf) CLSSTYLE_NEVERPRINT); 

} 

PPRINTDEST CreateDupPrintDest(PPRINTDEST pPrintDest) 

{ 

PPRINTDEST pDupPrintDest; 

PSZ *apdopData, pszValue; 

ULONG ulIndex, ulSize; 

PDRIVDATA pDrivData, pOldDrivData; 

BOOL bFreePrintDest = FALSE; 

/* Allocate a new PRINTDEST structure */ 
pDupPrintDest = malloc(sizeof(PRINTDEST)); 
if (!pDupPrintDest) 
return(NULL); 

memset(pDupPrintDest, 0, sizeof(PRINTDEST)); 

/* Copy over the values from pPrintDest and make new string 
* pointers for string fields. 

*/ 

pDupPrintDest->cb = sizeof(PRINTDEST); 
pDupPrintDest->lType = pPrintDest->lType; 
pDupPrintDest->pszToken = pPrintDest->pszToken 

? strdup(pPrintDest->pszToken) 

: NULL; 

pDupPrintDest->lCount = pPrintDest->lCount; 
pDupPrintDest->f1 = pPrintDest->f1; 
pDupPrintDest->pszPrinter = pPrintDest->pszPrinter 

? strdup(pPrintDest->pszPrinter) 
: NULL; 

/* Loop through pPrintDest->lCount and create a new pdopData 
array. */ 

ulSize = pPrintDest->lCount * sizeof(PSZ); 
apdopData = malloc(ulSize); 
if (apdopData) 

{ 


.ng so 


memset(apdopData, 0, ulSize); 

for (ullndex = 0; ullndex < pPrintDest->10ount; ullndex++) 

{ 
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*/ 

if (ullndex 1= DRIVER_DATA) 

{ 

pszValue = pPrintDest->pdopData[ullndex]; 

apdopData[ullndex] = pszValue ? strdup(pszValue) : NULL; 

} 

else 

{ 

/* This is the driver data. Copy the structure over */ 
pOldDrivData = (PDRIVDATA)pPrintDest->pdopData[ullndex]; 
pDrivData = malloc(p01dDrivData->cb) ; 
if (pDrivData) 

{ 

memcpy(pDrivData, pOldDrivData, p01dDrivData->cb); 
apdopData[ullndex] = (PSZ)pDrivData; 

} 

else 

{ 

bFreePrintDest = TRUE; 
break; 

} 

} 

} 

pDupPrintDest->pdopData = apdopData; 

} 

else 

bFreePrintDest = TRUE; 

if (bFreePrintDest) 

{ 

/* An error occurred somewhere above. Free the pDupPrintDest 
buffer. */ 

FreePrintDest(pDupPrintDest); 
return(NULL); 

} 

else 

return(pDupPrintDest); 

} 

/* FreePrintDest frees all the data associated with a PRINTDEST 
structure */ 

VOID FreePrintDest(PPRINTDEST pPrintDest) 

{ 
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ULONG ulIndex; 

/* Free the strings. */ 
free(pPrintDest->pszToken); 

free(pPrintDest->pszPrinter); 

/* Free the elements in the pdopData array */ 
for (ullndex = 0; ullndex < pPrintDest->lCount; ullndex++ ) 
{ 

free(pPrintDest->pdopData[ullndex]); 

} 


/* Free the array itself */ 
free(pPrintDest->pdopData); 

free(pPrintDest); 

} 

/* PrintFolder is the thread procedure that actually prints out the 
* contents of the folder. 

*/ 

VOID PrintFolder(PTHREADDATA pData) 

{ 

HDC hdc; 

HPS hps; 

SIZEL sizel; 

CHAR szDocTitle[256]; 

PSZ pszFileName, pszTitle; 

ULONG ulSize; 

LONG lCharHeight; 

SOMAny *Object / *NextObj; 

POINTL point; 

HMQ hmq = 0 ; 

HAB hab = 0; 

FONTMETRICS fm; 


/* This thread needs a message queue to do printing */ 
hab = Winlnitialize(0) ; 
if (!hab) 
return; 

hmq = WinCreateMsgQueue(hab, 0); 
if (hmq) 
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WinCancelShutdown(hmq, TRUE); 
else 
{ 

WinTerminate(hab); 
return; 

} 

/* Check if we need to display the job properties dialog */ 
if (pData->pPrintDest->f1 & PD_JOB_PROPERTY) 

{ 

LONG lSize; 

PDEVOPENSTRUC pdos; 

pdos = (PDEVOPENSTRUC) pData->pPrintDest->pdopData; 

/* Get the required size for the buffer */ 

lSize = DevPostDeviceModes(hab, NULL, pdos->pszDriverName, 

pdos->pdriv->szDeviceName, 
pData->pPrintDest->pszPrinter, 
DPDM_POSTJOBPROP); 

if (lSize > 0) 

{ 

/* If the size is larger than the data we already have, 

* allocate a new buffer and copy the old data into it. 

*/ 

if (lSize > pdos->pdriv->cb) 

{ 

PDRIVDATA pNewData; 
pNewData = malloc(lSize); 

memcpy(pNewData, pdos->pdriv, pdos->pdriv->cb); 
free(pdos->pdriv); 
pdos->pdriv = pNewData; 

} 

DevPostDeviceModes(hab, pdos->pdriv, pdos->pszDriverName, 

pdos->pdriv->szDeviceName, 
pData->pPrintDest->pszPrinter, 
DPDM_POSTJOBPROP); 

} 

} 



Printing 


357 


hdc = DevOpenDC(hab, pData->pPrintDest->lType, 
pData->pPrintDest->pszToken / 
pData->pPrintDest->lCount, 
pData->pPrintDest->pdopData, NULLHANDLE); 

if (hdc) 

{ 

/* Get the width and height of the paper. */ 

DevQueryCaps(hdc, CAPS_WIDTH, 2L,(PLONG) &sizel); 

/* Create a presentation space to draw in. */ 

hps = GpiCreatePS(hab, hdc, fcsizel, PU_TWIPS | GPIT_MICRO | 

GPIF_DEFAULT | GPIA_ASSOC); 

/* Query the character height */ 

GpiQueryFontMetrics(hps, sizeof(FONTMETRICS), &fm ); 

ICharHeight = fm.lMaxBaselineExt + fm.lExternalLeading; 

/* Give the printer the name of this new job. */ 
pszTitle = _wpQueryTitle(pData->Folder); 

sprintf(szDocTitle, "Folder Contents for %s", pszTitle); 
DevEscape(hdc, DEVESC_STARTDOC, sizeof(szDocTitle), szDocTitle, 
NULL, NULL); 

/* Draw the title at the top of the page */ 
point.x = 10; 

point.y = sizel.cy - ICharHeight; 

GpiSetCurrentPosition(hps, &point); 

GpiCharString(hps, strlen(szDocTitle), szDocTitle); 
point.y -= ICharHeight * 2; 

/* Populate the folder and loop through the contents */ 
_wpQueryRealName(pData->Folder, NULL, &ulSize, TRUE); 
if (ulSize) 

{ 

pszFileName = malloc(ulSize); 

_wpQueryRealName(pData->Folder, pszFileName, &ulSize, TRUE); 
_wpPopulate(pData->Folder, 0, pszFileName, FALSE); 
free(pszFileName); 

Object = _wpQueryContent(pData->Folder, NULL, QC_First); 
while (Object) 

{ 

/* Print the title of this object */ 
pszTitle = _wpQueryTitie(Object); 
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GpiSetCurrentPosition(hps, &point); 

GpiCharString(hps, strlen(pszTitle), pszTitle); 

point.y -= ICharHeight; 

/* Get the next object THEN unlock this one */ 

NextObj = _wpQueryContent(pData->Folder, Object, 

QC_Next); 

_wpUnlockObject(Object); 

Object = NextObj; 

/* If we're at the bottom of the page, eject and start a 
new one. */ 

if ((point.y <= lCharHeight*2) && Object) 

{ 

DevEscape(hdc, DEVESC_NEWFRAME, OL, NULL, NULL, NULL ); 
point.y = sizel.cy - ICharHeight; 

} 

} 

} 

DevEscape(hdc, DEVESC_ENDDOC, 0, NULL, NULL, NULL); 

GpiDestroyPS(hps); 

DevCloseDC(hdc); 

} 

_wpUnlockObject(pData->Folder); 

FreePrintDest(pData->pPrintDest); 
free(pData); 

if (hmq) 

WinDestroyMsgQueue(hmq); 

if (hab) 

WinTerminate(hab); 

} 


# wpPrintPifFile WPDataFile instance method 


Prints a file in PIF format. 
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SYNTAX 

BOOL wpPrintPifFile (PPRINTDEST pPrintDest) 

PARAMETERS 

pPrintDest - input 

A pointer to a PRINTDEST structure (pg. 369) containing the infor¬ 
mation needed to open the device context for the desired printer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to print a PIF file object. The 
WPDataFile class handles this method by invoking a function in the 
Picture Viewer (PICVTEW.EXE) to print the PIF file. 

HOWTO OVERRIDE 

This method can be overridden to replace the print behavior of PIF 
files. When the user requests to print a PIF file, the system will invoke 
wpPrintObject on the file. The WPDataFile class will respond by calling 
this method. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpPrintMetaFile -349, wpPrintObject -350, wpPrintPlainTextFile -359, 
wpPrintPrinterSpecificFile -360, wpPrintUnknownFile -361 


• wpPrintPlainTextFile WPDataFile instance method 

Prints a file in plain text format. 

SYNTAX 

BOOL wpPrintPlainTextFile (PPRINTDEST pPrintDest) 

PARAMETERS 

pPrintDest - input 
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A pointer to a PRINTDEST structure (pg. 369) containing the infor¬ 
mation needed to open the device context for the desired printer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to print a plain text file object. 

HOWTO OVERRIDE 

This method can be overridden to replace the print behavior of plain 
text files. When the user requests to print a file and selects Plain text 
from the type selection dialog, the WPDataFile class calls this method. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpPrintMetaFile -349, wpPrintObject -350, wpPrintPifFile -358, 
wpPrintPrinterSpecificFile -360, wpPrintUnknownFile -361 


® wpPrintPrmfcerSpecifkFiie WPDataFile instance method 

Prints a file in printer-specific format. 

SYNTAX 

BOOL wpPrintPrinterSpecificFile (PPRINTDEST pPrintDest) 

PARAMETERS 

pPrintDest - input 

A pointer to a PRINTDEST structure (pg. 369) containing the infor¬ 
mation needed to open the device context for the desired printer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 



Printing 


361 


HOWTO CALL 

This method can be called at any time to print a file with printer-spe¬ 
cific data. 

HOWTO OVERRIDE 

This method can be overridden to replace the print behavior of 
printer-specific data. When the user requests to print a file and selects 
Printer-specific from the type selection dialog, the WPDataFile class 
calls this method. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpPrintMetaFile -349, wpPrintObject -350, wpPrintPifFile -358, 
wpPrintPlainTextFile -359, wpPrintUnknownFile -361 


• wpPrintUnknownFile WPDataFile Instance method 


Prompts the user for the format of a file and then calls the appropriate 
print method. 

SYNTAX 

BOOL wpPrintUnknownFile (PPRINTDEST pPrintDest) 

PARAMETERS 

pPrintDest - input 

A pointer to a PRINTDEST structure (pg. 361) containing the infor¬ 
mation needed to open the device context for the desired printer. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time to print a file whose format is 
unknown. The type selection dialog will be displayed to allow the user 
to choose between Plain text and Printer-specific formats. 
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HOWTO OVERRIDE 

This method can be overridden to replace the behavior of the type se¬ 
lection dialog. 

OTHER INFO 

Include files: wpdataf.h 

SEE ALSO 

wpPrintMetaFile -349, wpPrintObject -350, wpPrintPifFile -358, 
wpPrintPlainTextFile -359, wpPrintPrinterSpecificFile -360 


# wpReleasePrinter WPPrinter instance method 

Releases the queue of a printer object. 

SYNTAX 

BOOL wpReleasePrinter ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on a printer object to release the 
queue. The user must be logged on as a network administrator for this 
method to have an effect on a network printer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpDeleteAHJobs -346, wpHoldPrinter -346 



WPPrinter instance method 


wpQueryComputerName 

Returns the computer name of a printer object. 

SYNTAX 

ULONG wpQueryComputerName (PSZ pszComputerName ) 

PARAMETERS 

pszComputerName - input/output 

A pointer to a string buffer which, upon return, will contain the com¬ 
puter name for this print device if the printer resides on the network. 
The size of this buffer should be CCHMAXPATH. 

RETURNS 

0—An error occurred. 

1— The printer is local. 

2— The printer is on the network. pszComputerName contains the net¬ 
work computer name. 

HOWTO CALL 

This method can be called at any time on a printer object to query the 
computer name. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 


® wpQueryPrinterName WPPrinter instance method 

Returns the physical printer name of a printer object. 

SYNTAX 

BOOL wpQueryPrinterName (PSZ pszPrinterName) 

PARAMETERS 

pszPrinterName - input/output 
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A pointer to a string buffer which, upon return, will contain the physi- 
cal printer name for this print device. The size of this buffer should be 
CCHMAXPATH. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on a printer object to query the 
physical printer name. Note that this name is different from the title of 
the printer object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 


# wpQueryQueueOptions WPPrinter instance method 

(Warp only)__ 


Returns the queue options of a printer. 

SYNTAX 

ULONG wpQueryQueueOptions () 

PARAMETERS 

(none) 

RETURNS 

The queue options for this printer which can contain the following 
flags ORed together: 

Define ___ Description _ 

PO_PRINTERSPECIFICFORMAT 0X01 Spool print jobs in 

PM_Q_RAW format. 

PO_PRINTWHILESPOOLING 0X02 Printing is enabled while a job 

is spooling. 
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PO_APPDEFAULT 0X04 This is the default printer 

object. 

POJOBDIALOGBEFOREPR1NT 0X10000 Display the job properties 

dialog when a job is printed. 


HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpSetOueueOptions -367 


wpQueryRemoteOptions WPPrloter instance method 

(Warp only) _ 

Returns the remote options of a printer. 

SYNTAX 

BOOL wpQueryRemoteOptions (PULONG pulRefreshlnterval , 

PULONG pflAUJobs) 


PARAMETERS 

pulRefreshlnterval - output 

A pointer to the interval, in seconds, between refreshes of the printer 
views. 

pflAUJohs - output 

TRUE—Display all the jobs in the network queue. 

FALSE—Display only the jobs for the current user in the network 
queue. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 
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HOWTO CALL 

This method can be called at any time. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpSetRemoteOptions -368 

® wpSetDefauItPrinter WPPrinter Instance method 

Sets a printer object as the default printer. 

SYNTAX 

BOOL wpSetDefauItPrinter ( ) 

PARAMETERS 

none 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time on a printer object set it as the 
default printer. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 





® wpSetQueueOptions 


WPPrinter Instance method 
(Warp only) 


Sets the queue options of a printer. 

SYNTAX 

BOOL wpSetQueueOptions (ULONG ulOptions) 

PARAMETERS 

ulOptions - input 

The queue options for this printer which can contain the following 

flags ORed together: 

Define ___ Description _ 

PO_PRINTERSPECIFICFORMAT 0x01 Spool print jobs in 

PM_Q_RAW format. 

PO_PRINTWHILESPOOLING 0x02 Printing is enabled while a job 

is spooling. 

PO_APPDEFAULT 0x04 This is the default printer 

object. 

POJOBDIALOGBEFOREPRINT 0x10000 Display the job properties 

dialog when a job is printed. 


RETURNS 

TRUE—The method completed successfully. 
FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpQueryQueueOptions -364 
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• wpSetRemoteOptions WPPrinter instance method 

(Warp only)_ 


Sets the remote options of a printer. 

SYNTAX 

BOOL wpSetRemoteOptions(ULONG ulRefreshlnterval, ULONG 
flAUJobs) 

PARAMETERS 

ulRefreshlnterval - input 

A pointer to the interval, in seconds, between refreshes of the printer 
views. 

flAUJobs - input 

TRUE—Display all the jobs in the network queue. 

FALSE—Display only the jobs for the current user in the network 
queue. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

This method can be called at any time. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpprint.h 

SEE ALSO 

wpQueryRemoteOptions -365 
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Printing: Structures 



cb (ULONG) 0 

The size of the PRINTDEST structure, in bytes, including cb itself. This value does not in¬ 
clude the length of the string fields or the pdopData. 

IType (LONG) 4 

The type of device context to specify in the call to DevOpenDC. 

Constant Description 

OD_QUEUED 2 The output is to be queued. 

OD_DIRECT 5 The output is not to be queued. 


pszToken (PSZ) 8 

The device information token to specify in the call to DevOpenDC. This is always 

lCount (LONG) 12 

The number of items in pdopData. At least the first four items must be specified for 
OD_QUEUED devices. 

pdopData (PDEVOPENDATA) 16 

An array of pointers to data in the format of the DEVOPENSTRUC structure. The size of 
this array is specified in ICount. 

fl (ULONG) 20 

The following flag may be specified: 

Constant _Description 

PD_JOB_PROPERTY 0X01 DevPostDeviceModes should be 

called with DPDM_POSTJOBPROP 
before calling DevOpenDC. 


pszPrinter (PSZ) 24 

The printer name to specify when calling DevPostDeviceModes. 

Used by: wpPrintMetaFile -349, wpPrintObject -350, wpPrintPifFile -358, 
wpPrintPlainTextFile -359, wpPrintPrinterSpecificFile -360, wpPrintUnknownFile -361 
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pszLogAddress (PSZ) 0 

The logical address for the device. If the device is ODDIRECT, this value must be set to the 
logical device address (e.g. “LPT1”). If the device is OD_QUEUED, this must be the name 


of the queue. 

pszBriverName (PSZ) 4 

The name of the device driver. This value is required. 

pdriv (PDRIVDATA) 8 

Device driver-specific data. 

pszBataType (PSZ) 12 

The type of data that is to be queued. Either “PM_Q_STD” for standard format or 
TM_QJRAW” for raw format. 

pszComment (PSZ) 16 

A description that can be displayed by the spooler to the user. This field is optional. 

pszQueueProcName (PSZ) 20 

The name of the queue processor for queued output. This field is optional. 

pszQueueProeParams (PSZ) 24 

The parameter string for the queue processor for queued output. This field is optional. 

pszSpoolerParams (PSZ) 28 


The parameter string for the spooler for queued output. The following two parameters can 
be specified and must be separated by a space: 

FORM= form name, where form name is the name of the form. Multiple form names can 
be specified, separated by a comma. Form names should be enclosed by double quotes if 
they contain the characters V Y or ‘=’. 

PRTY= n where n is the priority in the range of 1 to 99. The default priority is 50. 

pszNetworkParams (PSZ) 82 

The parameter string for the network program for queued output. The following parame¬ 
ter is defined: (Other parameters may be defined by the network program) 

USER = user name. If the user name is not specified, a null user identifier is used. 

Used by: PRINTDEST structure 


Finding Objects 

O bjects are easy to find if they have been assigned object IDs or if 
their persistent handles have been stored, but sometimes this in¬ 
formation is not available. It is not always feasible to keep track of ob¬ 
jects using their handles or IDs. WPObject provides class methods to 
allow applications to enumerate all the objects of any class or to find an 
object matching specific search criteria. 

Error Handling 

One of the disadvantages of object-oriented design is the difficulty in 
determining the cause of errors. If a method is called on an object and 
an error occurs many levels deep in the call chain, how does the caller 
know where the failure took place? Workplace provides methods for 
setting and querying the last error that occurred for an object or a 
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class. Instance methods should set errors using wpSetError and class 
methods should use wpclsSetError. 

Restrictions and Warnings 

• Finding objects usually takes a long time to process and, therefore, 
should be done from a separate thread. 

• There are few situations when Workplace default classes set object 
or class errors. Some WPFileSystem methods set base file system er¬ 
rors on objects during copy or move actions, and the find methods 
set errors to indicate the status of the search. The error handling 
methods are mostly useful for defining new application errors. 


Instance Methods 


wpFindMiiiWindow (Warp) returns the minimized window object 
given a window frame handle (pg. 372). 

wpModuleForClass (Warp) returns the name of the module in which a 
class is defined (pg. 373). 

wpQueryError returns the last error for an object (pg. 374). 
wpRepIacementlsInEffect (Warp) returns whether the specified class 
has been replaced (pg. 375). 

wpSetError sets the last error for an object (pg. 375i. 


# wpFfndMin Window WPMinWinViewer 

instance method (Warp only) 


Returns the minimized window object given a window frame handle. 

SYNTAX 

WPObjeet * wpFindMinWindow(HWND hwndFrame) 

PARAMETERS 

hwndFrame - input 

The handle of a frame window. 






Miscellaneous Methods 


373 


RETURNS 

(nonzero value)—The minimized window object that represents this 
frame window when it is minimized. Minimized windows are instances 
of the WPMinWindow class. 

NULL—This frame has not been minimized. 

HOWTO CALL 

Call this method at any time on the Minimized Window Viewer 
<WP_VIEWER>. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpmwv.h 


• v/pModuleForClass WPCIassManager Instance method 

(Warp only) 


Returns the name of the module in which a class is defined. 

SYNTAX 

PSZ wpModuleForClass (PSZ pszClass) 

PARAMETERS 

pszClass - input 
The name of the class. 

RETURNS 

(non-zero value)—The name of the module containing the specified 
class. 

NULL—Mi error occurred. 

HOWTO CALL 

Call this method at any time on SOMClassMgrObject to determine the 
name of the .DLL where a class resides. This is useful when the mod¬ 
ule must be loaded to obtain resources for the class. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpclsmgr.h 


• wpQueryError WPObJect instance method 

Returns the last error for an object. 

SYNTAX 

ULONG wpQueryError ( ) 

PARAMETERS 

none 

RETURNS 

The last error that occurred for this object. 

HOWTO CALL 

Call this method at any time to query the last error for an object. Call 
wpSetError to set the error for an object to zero before performing an 
action. Then, if the action fails, call wpQueryError to get the cause of 
the error. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsQueryError -384, wpclsSetError -385, wpSetError -375 

NOTES 

Most default Workplace methods do not call wpSetError when an er¬ 
ror occurs. Therefore, wpQueryError cannot always be used to deter¬ 
mine the cause of an error. 
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# wpReplacementlsInEffect WPCIassHanager Instance 

__ method (Warp only) _ 

Returns whether the specified class has been replaced. 

SYNTAX 

BOOL wpReplacementlsInEffect (PSZ pszOldClass, PSZ pszNewClass) 

PARAMETERS 

pszOldClass - input 

The name of the original class. 

pszNewClass - input 

The name of the replacement class. 

RETURNS 

TRUE —pszOldClass has been replaced by pszNewClass . 

FALSE—The specified replacement is not in effect. 

HOWTO CALL 

Call this method at any time on SOMClassMgrObject. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpclsmgr.h 

SEE ALSO 

WinReplaceObjectClass -19 


# wpSetError WPObject Instance method 


Sets the last error for an object. 

SYNTAX 

ULONG wpSetError (ULONG uIErrorld) 
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PARAMETERS 

ulErrorld - input 

The error for the object. This can be any application-defined or sys¬ 
tem-defined error code. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the last error for an object. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsOueryError -384, wpclsSetError -385, wpQueryError -374 


Class Methods 


wpclsFindObjectEnd ends a find operation (pg. 376). 
wpclsFindObjectFirst begins a find operation and specifies the criteria 
for the search (pg. 377). 

wpclsFindObjectNext continues a find operation (pg. 382). 
wpclsFindOneObject (Warp) displays the find dialog (pg. 383). 
wpclsQueryError returns the last error for a class (pg. 384). 
wpclsSetError sets the last error for a class (pg. 385). 


# wpclsFindObjectEnd WPObject class method 


Ends a find operation. 
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SYNTAX 

BOOL wpclsFindObjectEnd(HFIND hFind) 

PARAMETERS 

hFind - input 

The handle of the find operation to terminate. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

Possible returns from _wpclsQueryError 
WPERR_INVALID_HFIND 0x1715 

HOWTO CALL 

Call this method to terminate a find operation that was initiated with 
wpclsFindObjectFirst. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsFindObjectFirst -377, wpclsFindObjectNext -382 


# wpclsFindObjectFirst WPObject class method 


Begins a find operation and specifies the criteria for the search. 

SYNTAX 

BOOL wpclsFindObjectFirst(PCLASS pClassList, PHFIND phFind, PSZ 

pszTitle, WPFolder * Folder, BOOL fSub- 
folders, PVOID pExtendedCriteria, POBJECT 
pBuffer ; PULONG pCount) 

PARAMETERS 

pClassList - input 

A pointer to a NULL-terminated array of class object pointers. 
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phFind - input/output 

A pointer to an HFIND which, upon return, will contain the handle for 
this find operation. Use the handle when calling wpclsFindObjectNext 
and wpclsFindObjectEnd. 
pszTitle - input 

A pointer to a string containing the title filter for objects. Only objects 
whose title matches this string will be returned. The character can 
be used anywhere in this string as a wildcard. Specify if no filter is 
desired. 

Folder - input 

The object pointer for the folder where the search will start. 
wpclsOueryFolder can be used to obtain a folder object pointer. 
fSubFolders - input 

TRUE—Search all subfolders of Folder. 

FALSE—Do not search subfolders. 
pExtendedCriteria - input 

This parameter currently is not supported and should be set to NULL. 
pBuffer - input/output 

A pointer to a buffer which, upon return, will contain the pointers to 
the objects that were found. 
pCount- input/output 

A pointer to a ULONG containing the number of object pointers that 
will fit in pBuffer . Upon return, this parameter will contain the actual 
number of objects returned. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

Possible returns from _wpclsQueryError 


WPERR_INVALID_FOLDER 0x1712 

WPERR_BUFFER_OVERFLOW 0x1713 

WPERROBJECTNOTFOUND 0x1714 

WPERRINVALIDHFIND 0x1715 

WPERR_INVALID_COUNT 0x1716 

WPERRJNVALIDJSUFFER 0x1717 


HOWTO CALL 

Call this method to begin a find operation. If FALSE is returned, call 
wpclsQueryError to get the error code. If the error is WPERR_- 
BUFFER_OVERFLOW, there are more objects for the system to return 
than will fit in pBuffer. Call wpclsFindObjectNext to get the remaining 
objects. See the sample below for more information. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsFindObjectEnd -376, wpclsFindObjectNext -377, 
wpclsQueryFolder -74 

RESTRICTIONS/WARNINGS 

® Each object that is returned from wpclsFindObjectFirst or wpcls¬ 
FindObjectNext is locked once by the system. Call wpUnlockObject 
on each object when the pointer is no longer needed. 

® Sometimes wpclsFindObjectFirst or wpclsFindObjectNext will set 
the last error to WPERR_BUFFER_OVERFLOW even when there 
are no more objects. Always check the pCount returned to see if zero 
objects were returned. 

SAMPLE CODE 

The following example demonstrates how to use wpclsFindObjectFirst, 
wpclsFindObjectNext, and wpclsFindObjectEnd to search for printers. 
This function is passed to DosCreateThread and is executed on a sep¬ 
arate thread. 

VOID HoldPrinterObjects(VOID) 

{ 

CLASS apClass[2]; 

HFIND hFind; 

SOMAny *Desktop, 

POBJECT pBuffer; 

BOOL bReturn; 

ULONG ulError = 0, ulCount = 10; 

HMQ hmq = 0; 

HAB hab = 0; 

hab = Winlnitialize(0); 
if (!hab) 
return; 

/* Create a message queue since some Workplace methods might 
require one. */ 
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hmq = WinCreateMsgQueue(hab, 0); 

if (hmq) 

WinCancelShutdown(hmq, TRUE); 
else 
{ 

WinTerminate(hab); 
return; 

} 

apClass[0] = _WPPrinter 
apClass[1] = NULL; 

/* Get the object pointer for the desktop, (no need to lock it 
* since the Desktop never goes to sleep) 

*/ 

Desktop = _wpclsQueryFolder(_WPObject, "<WP_DESKTOP>", FALSE); 
if (Desktop) 

{ 

/* Allocate a buffer that can hold 10 SOMAny pointers */ 
pBuffer = malloc(sizeof(OBJECT) * 10); 
if (pBuffer) 

{ 

_wpclsSetError(_WP0bject, 0); 

bReturn = _wpclsFindObjectFirst(_WPObject, apClass, &hFind, 

" * " 

Desktop, TRUE, NULL, pBuffer, 
&ulCount); 

if (!bReturn) 

ulError = _wpclsQueryError(_WPObject); 

if (!ulError || ulError == WPERR_BUFFER_OVERFLOW) 

{ 

ProcessBuffer(pBuffer, ulCount); 

/* Keep looping until there are no more objects */ 
while (ulCount && ulError == WPERR_BUFFER_OVERFLOW) 

{ 

ulError = 0; 
ulCount = 10; 

_wpclsSetError(_WPObject, 0); 

bReturn = _wpclsFindObjectNext(_WPObject, hFind, 


// Search for Printer objects 
// NULL terminate the array 


pBuffer, &ulCount); 
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if (IbReturn) 

ulError = _wpclsQueryError(_WPObject); 

if (!ulError || ulError == WPERR_BUFFER_OVERFLOW) 

{ 

ProcessBuffer(pBuffer, ulCount); 

} 

} 

_wpclsFindObjectEnd(_WPObject, hFind); 

} 

free(pBuffer); 

} 

} 

WinDestroyMsgQueue(hmq); 

WinTerminate(hab); 

} 


/* ProcessBuffer processes each printer object in the buffer and 
* calls wpHoldPrinter to hold the printer's queue. 

*/ 

VOID ProcessBuffer(SOMAny **pBuffer, ULONG ulCount) 

{ 

ULONG i; 

PSZ pszTitle; 

CHAR szMessage[256]; 

for (i = 0; i < ulCount; i++) 

{ 

_wpHoldPrinter(pBuffer[i]); 

_wpUnlockObject(pBuffer[i]); 

} 

} 
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® wpcIsFindObjectNext WPObjeet class method 


Continues a find operation. 

SYNTAX 

BOOL wpcIsFindObjectNext(HFIND hFind, POBJECT pBuffer, 

PULONG pCount) 

PARAMETERS 

hFind - input 

The find handle returned from wpclsFindObjectFirst. 
pBuffer - input/output 

A pointer to a buffer which, upon return, will contain the pointers to 
the objects that were found. 
pCount- input/output 

A pointer to a ULONG containing the number of object pointers that 
will fit in pBuffer. Upon return, this parameter will contain the actual 
number of objects returned. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

Possible returns from _wpclsQueryError 


WPERRJBUFFER_OVERFLOW 0x1713 

WPERR_OBJECT_NOT_FOUND 0x1714 

WPERRJNVALIDJHFIND 0x1715 

WPERR_INVALID_COUNT 0x1716 

WPERR_INVALID_BUFFER 0x1717 


HOWTO CALL 

Call this method to continue a find operation when the error from 
wpclsFindObjectFirst or wpcIsFindObjectNext is WPERR_BUFFER_- 
OVERFLOW; call it repeatedly until no more objects are found 
(WPERR_OBJECT_NOT_FOUND is returned). See the sample for 
wpclsFindObjectFirst for more information. 

HOWTO OVERRIDE 

This method is generally not overridden. 
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OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsFindObjectEnd -376, wpclsFindObjectFirst -377 

RESTRICTIONS/WARNINGS 

® Each object that is returned from wpclsFindObjectFirst or wpcls- 
FindObjectNext is locked once by the system. Call wpUnlockObject 
on each object when the pointer is no longer needed. 

® Sometimes wpclsFindObjectFirst or wpclsFindObjectNext will set 
the last error to WPERR_BF!FFER_OVERFFOW even when there 
are no more objects. Always check the pCount returned to see if zero 
objects were returned. 


wpelsFindOneObject WPObject class method 


Displays the find dialog. 

SYNTAX 

WPObject * wpelsFindOneObject (HWND hwndOwner, PSZ 

pszFindParams) 


PARAMETERS 

hxmdOxmer - input 

The handle of the window that should be the owner of the find dialog. 
pszFindParams - input 

A setup string containing the search criteria. See wpSetup for more in¬ 
formation about setup strings. 

RETURNS 

(non-zero value)—The object found by the system. 

NULL—An error occurred or the object was not found. 

HOWTO CALL 

Call this method at any time to display the find dialog, enabling the 
user to search for an object. 
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HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsFindObjectEnd -376, wpclsFindObjectFirst -377, 
wpclsFindObjectNext -382, wpSetup -63 


% wpcIsQueryError WPObJect class method 


Returns the last error for a class. 

SYNTAX 

ULONG wpcIsQueryError ( ) 

PARAMETERS 

none 

RETURNS 

The last error that occurred for this class. 

HOWTO CALL 

Call this method at any time to query the last error for a class. Call 
wpclsSetError to set the error for a class to zero before performing an 
action. Then, if the action fails, call wpcIsQueryError to get the cause 
of the error. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsSetError -385, wpQueryError -374, wpSetError -375 
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NOTES 

Most default Workplace class methods do not call wpclsSetError when 
an error occurs. Therefore, wpclsQueryError cannot always be used to 
determine the cause of an error. 


® wpclsSetError WPObject class method 

Sets the last error for a class. 

SYNTAX 

ULONG wpclsSetError (ULONG ulErrorld) 

PARAMETERS 

ulErrorld - input 

The error for the class. This can be any application-defined or system- 
defined error code. 

RETURNS 

TRUE—The method completed successfully. 

FALSE—An error occurred. 

HOWTO CALL 

Call this method at any time to set the last error for a class. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: wpobject.h 

SEE ALSO 

wpclsQueryError -384, wpQueryError -374, wpSetError -375 




System Object 
Model 


I t would take a separate book to document all of the information 
about IBM’s System Object Model (SOM) but since this is a 
Workplace Shell programming reference, this chapter just highlights 
those aspects of SOM that are most relevant to WPS programmers. 

Workplace Shell application developers must take special care in 
designing their SOM classes because they must coexist with other 
classes running in the same process. SOM provides the ability to re¬ 
place entry points of some routines in order to change their behavior. 
The entry points for these replacement functions are stored in global 
variables which are common across the Workplace process. Workplace 
Shell already provides a replacement for SOMError to prevent the 
process from terminating. Workplace applications should use cus¬ 
tomized functions only for debugging purposes and not in retail ver¬ 
sions of the code; otherwise, they will conflict with other applications 
in the Workplace process. 

The shell also has programming interfaces that take the place of 
some basic SOM functionality. These include: 
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• wpclsNew is used instead of somNew. 

• wpDelete is used instead of somFree. 

• wpInitData and wpUnlnitData should be overridden instead of 
somlnit and somUnlnit. 

• WinRegisterClass is used instead of somRegisterClass. 

This chapter does not include all SOM functions and macros but 
does contain those that are most useful for Workplace Shell program¬ 
ming. The methods are documented as they would appear in the SOM- 
STARS implementation of SOM 2.x header files in order to make them 
consistent with the SOM 1.0 header files. 


Customization Functions 


SOMInitModule initializes multiple classes packaged in a single .DLL 
(pg- 387). 

SOMOutCharRoutine provides a replacement for character output 
(pg. 388). 


• SOMInitModule SOM customization function 


Initializes multiple classes packaged in a single .D LL . 

SYNTAX 

SOMEXTERN void SOMLXNK SOMInitModule (long majorVersion, 

long minorVersion, 
zString className ) 


PARAMETERS 

majorVersion - input 

The major version requested by the client loading this class. In the case 
of Workplace Shell classes, Workplace itself is usually the client loading 
the class. 

minorVersion - input 

The minor version requested by the client loading this class. 
className - input (SOM 2.X only) 

The name of the requested class to load. If the class object for this class 
is not created, SOM will consider this load to have failed. 
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RETURNS 

none 

HOWTO USE 

Replace this function by defining it in the .DLL containing the classes 
and exporting the function in the .DEF file. The SOMInitModule 
function should call <classname>NewClass for every class contained in 
the .DLL. This function is generally only called by the SOM class man¬ 
ager to load classes. 

OTHER INFO 

Include file: som.h 

SEE ALSO 

<class name>NewClass -394 

RESTRICTIONS/WARNINGS 

• This routine must use the _System linkage. 


# SOMOutCharRoutine SOM customization function 


Provides a replacement for character output. 

SYNTAX 

long MyOutCharRoutine (char c) 

SOMOutCharRoutine = MyOutCharRoutine; 

PARAMETERS 

c - input 

The character to write. The character output routine will be called 
once for every character to be written. 

RETURNS 

none 

HOWTO USE 

Replace this function by defining a character output routine using any 
function name. Then, during .DLL initialization, set the SOM global 
variable, SOMOutCharRoutine, to point to this function. From then 
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on, all Workplace Shell classes that use functions that call the 
SOMOutCharRoutine will use this customized function. The default 
character output routine writes the character to stdout. 

OTHER INFO 

Include file: som.h 

SEE ALSO 

<class name>MethodDebug -393, somLPrintf-390, somPrintf-391 

NOTES 

Only replace SOMOutCharRoutine in debug versions of your class im¬ 
plementation. If more than one Workplace application attempts to re¬ 
place this function, they will conflict with each other and the most re¬ 
cent class to load will overwrite the SOMOutCharRoutine global 
variable. 

RESTRICTIONS/WARNINGS 

® This replacement routine must use the _System linkage. 


Functions 


somldFromStrmg returns the SOM ID for a text string (pg. 389). 
somLPrintf prints a formatted string using SOMOutCharRoutine at 
the specified indentation level (pg. 390). 

somPrintf prints a formatted string using SOMOutCharRoutine 
(pg. 391). 


# somldPromString SOM function 


Returns the SOM ID for a text string. 

SYNTAX 

somld somldFromString (/Storing aString) 
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PARAMETERS 

aString - input 

The string to convert to a SOM ID. 

RETURNS 

The SOM ID for the specified string. 

HOWTO USE 

Call this function at any time to get the SOM ID for a string. Many 
SOM methods have SOM IDs for parameters which are created using 
this function. It is the responsibility of the caller to free the ID using 
SOMFree. 

OTHER INFO 

Include file: som.h 

SEE ALSO 

somLocateClassFile -399 


® somLPrintf SOM function 


Prints a formatted string using SOMOutCharRoutine at the specified 
indentation level. 

SYNTAX 

int somLPrintf (int level, zString/raf, args ...) 

PARAMETERS 

level - input 

The indentation level at which to place the string. 2 X level spaces will 
be written before the string. 
fmt- input 

The format string to print. 
args - input 

Arguments to substitute in the format string. 

RETURNS 

The number of characters printed. 
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HOWTO USE 

Call this function at any time to write a string. SOMOutCharRoutine 
will be used to output characters. The default destination is stdout but 
this can be customized. somLPrintf is similar to the C function printf, 
except it allows indentation levels and uses SOMOutCharRoutine in¬ 
stead of stdout. 

OTHER INFO 

Include files: somapi.h (SOM 2.X) or som.h (SOM 1.0) 

SEE ALSO 

SOMOutCharRoutine -388, somPrintf-391 


# somPrintf SOM function 


Prints a formatted string using SOMOutCharRoutine. 

SYNTAX 

hit somPrintf (zString fmt , args ...) 

PARAMETERS 

fmt- input 

The format string to print. 
args - input 

Arguments to substitute in the format string. 

RETURNS 

The number of characters printed. 

HOWTO USE 

Call this function at any time to write a string. SOMOutCharRoutine 
will be used to output characters. The default destination is stdout but 
this can be customized. somPrintf is similar to the C function printf, 
except it uses SOMOutCharRoutine instead of stdout. 

OTHER INFO 

Include files: somapi.h (SOM 2.X) or som.h (SOM 1.0) 
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SEE ALSO 

SOMOutCharRoutine -388, somLPrintf-390 


Generated Macros and Functions 


<class name>GetData returns a pointer to the instance data for an ob¬ 
ject (pg. 392). 

cclass name>MethodDebug prints a debug message for a method us¬ 
ing somPrintf (pg. 393). 

<classname>NewClass creates a class object for <classname> (pg. 394). 
cclass name> references to the class object representing <class name> 
(pg. 395). 


% <class name>GetData SQM generated macro 


Returns a pointer to the instance data for an object. 

SYNTAX 

<class name>Data * <class name>GetData (<class name> * Object) 

For example, for the class MyClass, the macro MyClassGetData is 
defined, and takes a pointer of type MyClass* as a parameter and re¬ 
turns a pointer of type MyClassData*. 

PARAMETERS 

Object - input 

The object for which the instance data is requested. 

RETURNS 

A pointer to the instance data for this object. This should be set to 
somThis to allow the _<variable name> macros to be used. 


HOWTO USE 

Call this macro to obtain a pointer to the instance data for an object. 
This macro is defined in the class’ .ih file (for C) or .xih file (for C++). 
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SAMPLE CODE 

The <class name>GetData macro should be called from within each 
method procedure that references instance variables. The following is 
an example of how to assign the somThis pointer from an instance 
method: 

MyClassData *somThis = MyClassGetData(somSelf); 


® <ciass name>MethodDebug SQM ge nerated macro 

Prints a debug message for a method using somPrintf. 

SYNTAX 

int <class name>MethodDebug(PSZ pszClassName, PSZ pszMethodName) 

PARAMETERS 

pszClassName - input 

This is usually set to the name of the class; however, the caller can use 
any string because it will be passed directly to somPrintf. 
pszMethodName - input 

This is usually set to the name of the method; however, the caller can 
use any string because it will be passed directly to somPrintf. 

RETURNS 

The return from somPrintf. 

HOWTO USE 

Call this macro to print a debug statement. This macro resolves to the 
macro SOM_Trace, which prints a line using somPrintf. The line con¬ 
tains the source file name, the line number, pszClassName, and 
pszMethodName. In order to disable the effects of <classname>Method- 
Debug, include the class header files in the implementation source 
file, and then include the line: 

ttdefine cclass name>MethodDebug(c,m) SOM_NoTrace(c,m) 


SEE ALSO 

somPrintf -391 
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SAMPLE CODE 

The <class name>MethodDebug macro should be called from within 
each method procedure to debug the flow of execution for an object. 
The following is an example of how to use this macro: 

MyClassMethodDebug("MyClass","mcls_wpInitData"); 


$ <class name>NewClass SOM generated function 


Creates a class object for <class name>. 

SYNTAX 

<class name> * <class name>NewClass(integer4 MajorVersion , integer4 

MinorVersion) 

For example, the function prototype for MyClass is: 

MyClass * MyClassNewClass (integer4 MajorVersion , 

integer4 MinorVersion) 


PARAMETERS 

MajorVersion - input 

The requested major version number. 

MinorVersion - input 

The requested minor version number. 

RETURNS 

The class object pointer. 

HOWTO USE 

This function should only be called by Workplace Shell applications 
from within the SOMInitModule function to load multiple classes 
from one .DLT. If the class object has already been created, this func¬ 
tion will return the existing class object pointer. The definition for this 
function is in the .ih (C) or the .xih (C++) file for the class. 


SEE ALSO 

SOMInitModule -387 
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® <cla$s name> SOM generated macro 


References the class object for <class name>. 

SYNTAX 

_<class name> 

For example, the class object pointer for MyClass would be _MyClass. 

HOWTO USE 

Use this macro to reference the class object pointer for any class that is 
already loaded. Use somFindClass if the class may not be loaded. This 
macro is useful for passing class object pointers to class methods. 


SOMObjeet Methods 


somGetClass returns a class object pointer for the class of an object 
(pg. 395). 

somGetClassName returns the name of the class of an object (pg. 396). 
somlsA indicates whether an object is an instance of a class or its de¬ 
scendants (pg. 397). 

somlsInstanceOf indicates if an object is an instance of a given class 
(pg- 397). 


© somGetClass SOMObject method 

Returns the class object pointer for the class of an object. 

SYNTAX 

SOMClass * somGetClass ( ) 

PARAMETERS 

none 

RETURNS 

The class object pointer for the object’s class. 
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HOWTO CALL 

Call this method on any object to obtain the class pointer for its class. 
This method is preferred over the SOM_GetClass macro. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: somobj.h 

SEE ALSO 

somGetClassName -396 


• somGetClassNam e SOMObject method 

Returns the name of the class of an object. 

SYNTAX 

zString somGetClassName ( ) 

PARAMETERS 

none 

RETURNS 

The class name for the object’s class. 

HOWTO CALL 

Call this method on any object to obtain the name of its class. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: somobj.h 

SEE ALSO 

somGetClass -395 
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® somlsA SOMObject method 

Indicates whether an object is an instance of a class or its descendants. 

SYNTAX 

int somlsA (SOMClass * aClassObj) 

PARAMETERS 

aClassObj - input 

The class object to test the object against. 

RETURNS 

TRUE—The object is an instance of aClassObj or one of its descen¬ 
dants. 

FALSE—The object is not one of these. 

HOWTO CALL 

Call this method on any object to test its class. This method is different 
from somlsInstanceOf in that it will also return TRUE if the class of the 
object is a descendant of aClassObj. somlsInstanceOf only returns 
TRUE if the class of the object is of the class aClassObj itself. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: somobj.h 

SEE ALSO 

somDescendedFrom -398, somGetClass -395, somlsInstanceOf-397 


® somlsInstanceOf SOMObject method 


Indicates if an object is an instance of a given class. 

SYNTAX 

int somlsInstanceOf (SOMClass * aClassObj) 
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PARAMETERS 

aClassOhj - input 

The class object to test the receiving object against. 

RETURNS 

TRUE—The object is an instance of aClassObj. 

FALSE—The object is not an instance of aClassObj. 

HOWTO CALL 

Call this method on any object to test its class. This method is different 
from somlsA in that it will only return TRUE if the class of the object is 
of the class aClassObj itself. somlsA will also return TRUE if the class of 
the object is a descendant of aClassObj. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: somobj.h 

SEE ALSO 

somDescendedFrom -398, somGetClass -395, somlsA-397 


SOMCIass Methods 


somDescendedFrom indicates whether a class is descended from a 
given class (pg. 398). 


# somDescendedFrom SOMCIass method 

Indicates whether a class is descended from a given class. 

SYNTAX 

int somDescendedFrom (SOMCIass * aClassObj) 

PARAMETERS 

aClassObj - input 

The class object to test the class object against. 
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RETURNS 

TRUE—The class object is descended from aClassObj. 
FALSE—Otherwise. 

HOWTO CALL 

Call this method on any class object to test its ancestry. 

HOWTO OVERRIDE 

This method is generally not overridden. 

OTHER INFO 

Include files: somcls.h 

SEE ALSO 

somGetClass -395, somIsA-397, somIsInstanceOf-397 


SOAIOossAlgr Methods 


somLocateClassFile returns the name of the module in which a class is 
defined (pg. 399). 


® somLocateClassFile SOMCIassMgr method 

Returns the name of the module in which a class is defined. 

SYNTAX 

zString somLocateClassFile (somld classld, long majorVersion, long minor- 

Version) 

PARAMETERS 

classld - input 

The SOM ID for the class. This can be obtained by calling somld- 

FromString. 

majorVersion - input 

The major version of the class. 
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minorVersion - input 

The minor version of the class. 

RETURNS 

The name of the module that contains the specified class. 

HOWTO CALL 

Call this method on SOMClassMgrObject to obtain the module name 
for a class. Workplace’s class manager, an instance of WPClassManager, 
responds by returning the module name specified when the class was 
registered with WinRegisterObjectClass. 

HOWTO OVERRIDE 

This method should not be overridden. 

OTHER INFO 

Include files: somcm.h 

SEE ALSO 

somGetClassName -396, WinRegisterObjectClass -18 




Setup String 
Keynames 


The following is a table of setup string keynames and their possible val¬ 
ues. Setup strings are used in many Workplace methods to set object 
data. 

Class _ Keyname _ Vague _Description 

Use the system default. 

Allow multiple instances of views to be 
opened. 

Disallow multiple instances of views. 

Use settings for the default view. 

Use the class default view. 

The ID of an application-defined view. 


WPObject CCVIEW “DEFAULT” 

“YES” 

“NO” 

DEFAULTVIEW “SETTINGS 
“DEFAULT” 
n 


401 




402 


Workplace Shell 


Class Keyname Value _ 

WPObject HELPLIBRARY file name 

HELPPANEL resource ID 

HIDEBUTTON “YES”* 

“NO” 

ICONFILE file name 

ICONPOS x,y 

ICONRESOURCE id,module 

MINWIN “DESKTOP 

“HIDE” 

“VIEWER”* 


NOCOPY 

“YES” 

“NO”* 

NODELETE 

“YES” 

“NO”* 

NODRAG 

“YES” 

“NO”* 

NODROP 

“YES” 


“NO”* 

NOLINK 

“YES” 

“NO”* 

NOMOVE 

“YES” 

“NO”* 

NOPRINT 

“YES” 

“NO”* 


Description_ 

Name of the library file to use for the 
general help panel. Does not need to be 
fully qualified if the file is in the help 
path. 

The ID of the general help panel. 

Use a hide button for the views. 

Use a minimize button. 

Fully qualified path of the icon. 

The initial icon position in a 
nongridded icon view. 

The resource ID and module name for 
the icon. The .DLL must already be 
loaded by the Workplace process. 

Minimize views to the desktop. 

Hide windows when minimize button is 
pressed. 

Minimize windows to the Minimized 
Window Viewer. 

Object cannot be copied. 

Object can be copied. 

Object cannot be deleted. 

Object can be deleted. 

Object’s icon cannot be dragged. 
Object’s icon can be dragged. 

No objects can be dropped on this 
object. 

Objects can be dropped on this object. 

A shadow of this object cannot be made. 
A shadow of this object can be made. 

Object cannot be moved. 

Object can be moved. 

Object cannot be printed. 

Object can be printed. 


*This is the default for the class 
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Class 

WPObject 


WPFolder 


Keyname Value Description 


NORENAME 

“YES” 

Object cannot be renamed. 


“NO”* 

Object can be renamed. 

NOSETTINGS 

‘YES” 

Object does not support the settings 
view. 


“NO”* 

Object supports the settings view. 

NOTVISIBLE 

‘YES” 

Object is invisible. 


“NO”* 

Object is visible. 

OBJECTID 

objectid 

The persistent object ID for this object. 


The string must begin with ‘<’ and end 
with *>’ and must be unique in the 
system. 


OPEN 

“SETTINGS” 

“DEFAULT” 

Open the settings notebook immediately. 
Open the default view immediately. 

TEMPLATE 

“YES” 

“NO”* 

Object is a template. 

Object is not a template. 

TITLE 

title 

The title for the object. 

ALWAYSSORT 

“YES” 

“NO”* 

Always sort the views. 

Do not sort the views. 

BACKGROUND 

f,m,s,t,c 

f—fully qualified path of image file, 
(specify ‘?’ for the boot drive) 
m—image mode: N for normal, 

T for tiled, S for scaled 
s—scaling factor 
t—background type: I for image, 

C for color 

c—background color: R G B or 
“DEFAULT.” 


DEFAULTVIEW 


Example: “BACKGROUND=c:\file.bmp,N,l,C,0 0 128” 

“TREE” Use Tree for default view. 

“ICON” Use Icon for default view. 

“DETAILS” Use Details for default view. 


DETAILSCLASS classname 


Class that defines details columns. 


*This is the default for the class 
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Class Keyname 

Value 

Description 

WPFolder DETAILSFONT 

font 

Font and point size to use for details 
view. Example: 8.Helv 

DETAILSVIEW 

“NORMAL” 

Use normal-size icons. 

DETAILSVIEW 

“MINE’ 

Use mini icons. 

ICONFONT 

font 

Font and point size to use for icon view. 
Example: 8.Helv 

ICONVIEW 

“FLOWED” 

Flow the list items. 


“NONFLOWED” 

Do not flow the list items. 


“NONGRID” 

Icon view is nongridded. 


“NORMAL” 

Use normal-size icons. 


“MINI” 

Use mini icons. 


“INVISIBLE” 

Hide the icons in flowed or nonflowed 



views. 

ICONNFILE 

index,filename 

index—this must be set to 1. 
filename—fully qualified path of the 



icon. 

ICONNRESOURCE index,id,module 

index—this must be set to 1. 



id—the ID of the icon resource, 
module—the name of the .DLL 
containing the resource. 

ICONVIEWPOS 

x,y,cx,cy 

The position and size of the Icon view. 

OPEN 

“DETAILS” 

Open the Details view immediately. 


“ICON” 

Open the Icon view immediately. 


“TREE” 

Open the Tree view immediately. 

REMOVEFONTS 

“YES” 

Remove all font settings from the folder. 

SORTCLASS 

classname 

Class that defines sort attributes. 

TREEFONT 

font 

Font and point size to use for Tree view. 
Example: 8.Helv 

TREEVIEW 

“NORMAL” 

Use normal-size icons. 


“MINI” 

Use mini icons. 


“INVISIBLE” 

Hide the icons. 


“LINES” 

Use lines in Tree view. 


“NOLINES” 

Do not display lines. 


*This is the default for the class 
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Class 

Keyname 

Value 

Description 

WPProgram 

WORKAREA 

‘YES” 

This folder is a workarea. 

and 


“NO”* 

This folder is not a workarea. 

WPProgram 

File 

ASSOCFILTER 

filterlist 

A list of extensions of data files to 
associate with this program. 

Example: *.C,*.DOC 



ASSOCTYPE 

typelist 

A list of types of data files to associate 
with this program. 

Example: Plain Text,C Code 


EXENAME 

filename 

File name of the executable. 


(WPProgram only) 


Must be fully qualified if the program 
does not reside in the system PATH. 


HIDEBUTTON 

not supported 



MAXIMIZED 

“YES” 

Maximize the application when started. 



“NO”* 

Do not maximize the application. 


MINIMIZED 

“YES” 

Minimize the application when started. 



“NO”* 

Do not minimize the application. 


NOAUTOCLOSE 

“YES” 

Do not close the window when the 




program terminates. This is for OS/2 or 
DOS-windowed applications. 



“NO”* 

Close the window after terminating. 


PARAMETERS 

paraml param2... 

Parameters to pass to the program. 

Each one is separated by a space. 


PROGTYPE 

“FULLSCREEN” 

Program type is: 

OS/2 fullscreen 



“PM” 

Presentation Manager 



“PROG_31_STD” 

WIN-OS/2 standard fullscreen. 



“PROG_31_STD 

WIN-OS/2 standard seamless common 



SEAMLESS 

COMMON” 

session 



“PROG_31_STD 

WIN-OS/2 standard seamless separate 



SEAMLESSVDM” 

session 



“PROG_31_ENH” 

WIN-OS/2 enhanced fullscreen 



“PRO G_31 _ENH 

WIN-OS/2 enhanced seamless common 



SEAMLESS 

COMMON” 

session 


*This is the default for the class 
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Class 

Keyname 

Value 

Description 



“PROG_Sl_ENH WIN-OS/2 enhanced seamless separate 
SEAMLESSVD M ” session. 

“VDM” DOS fullscreen 

“WINDOW OS/2 window 

ABLEVIO” 

“WINDOWEDVDM” DOS window 


SET 

dos setting=value The DOS setting and value for a DOS or 
WIN-OS/2 application. See Appen¬ 
dix B for a list of DOS settings. 
Example: “SET DOS_AUTOEXEC=C:\TEMPEXEC.BAT” 


STARTUPDIR 

pathname 

The working directory for this program. 

WPPrinter 

APPDEFAULT 

“YES” 

“NO” 

This is the default printer. 

This is not the default printer. 


DEFAULTVIEW 

“DETAILS” 

“ICON” 

Use Details for the default view. 

Use Icon for the default view. 


JOBDIALOG 

BEFOREPRINT 

YES 

“NO” 

Display the job properties dialog before 
printing. 

Do not display the job properties dialog. 


JOBPROPERTIES 

filename 

The full path to a file containing job 
properties for the print object. This 
can be created by saving 
PRQINF03->pDriverData to a file. 


OUTPUTTOFILE 

“YES” 

“NO” 

Output printing to a file. 

Do not output to a file. 


PORTNAME 

port(s) 

The name of the port for this printer. 
Multiple ports are separated by 

commas. 


PRINTDRTVER 

driver, device 

The full name of an installed printer 
driver. Multiple drivers are separated by 

commas. 

WPPrinter 

PRINTER “YES” 

SPECIFICFORMAT 

Jobs are spooled in raw format. 


*This is the default for the class 


“NO” 


Jobs are spooled in standard format. 
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Class 

Keyname 

Value 

Description 

WPPrinter 

PRINTWHILE 

SPOOLING 

“YES” 

“NO” 

Printing is enabled while a job is 
spooling. 

Printing is not enabled while spooling. 


QSTARTTIME 

time 

The time, in the format HH:MM, when 
the printer starts printing. 


QSTOPTIME 

time 

The time, in the format HH:MM, when 
the printer stops printing. 


QUEUENAME 

name 

The local name for the queue. This 
keyname is only used when a printer is 
created. 


QUEUEDRTVER 

driver 

The name of the queue driver. 


SEPARATORFILE 

filename 

The full path of the separator file for 
this printer 

WPLaunchPad FPOBJECTS 

Object,Object... 

The list of objects to insert into the 

Launch Pad. Object can be an object ID 
or the full path of a file system object. 

WPDisk 

DRIVENUM 

n 

The logical drive number 
(A=1,B=2, etc.). 

WPShadow 

SHADOWID 

Object 

The object this shadow refers to. This 
can be an object ID or the full path of a 
file system object. 

WPPalette 

XCELLCOUNT 

n 

The number of columns. 


YCELLCOUNT 

n 

The number of rows. 


XCELLWIDTH 

n 

The width of the cells in pixels. 


YCELLHEIGHT 

n 

The height of the cells in pixels. 


XCELLGAP 

n 

The gap between the columns in pixels. 


YCELLGAP 

n 

The gap between the rows in pixels. 

WPColor COLORS 

Palette 

*This is the default for the class 

color, color ... 

Colors for each cell in the palette 
separated by commas. Each color is a 
hex number in the format of 

OxRRGGBB (red, green, and blue 
values) 
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Class 

Keyname 

Value 

Description 

WPFont 

FONTS 

font, font... 

Fonts for each cell in the palette 

Palette 



separated by commas. Each font string 
contains the point size and face name. 
Example: 10.Helv,12.Helv 





_B 

DOS Settings 
Keynames 


The following is a table of DOS settings keynames and their possible 
values. These settings can be passsed in a setup string for a program 
object. For example, to set the DPMI memory limit for a program ob¬ 
ject, specify the following as part of the setup string: 


SET DPMI_MEMORY_LIMIT= 64 


Setting 

Value 

Description 

AUDIO_ADAPTER_SHARING 

“Required” 

Session-required access to audio adapter. 


“Optional” 

Use audio adapter if it is available. 


“None” 

No audio adapter is needed. 

COM_DIRECT_ACCESS 


Give session direct access to COM ports. 


“0” 

Do not give session direct access to 

COM ports. 

COM_HOLD 

“i” 

Keep COM ports open until session 
ends. 


“0” 

Do not keep COM ports open. 
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Setting 

Value 

Description. 

COMRECEIVEBUFFERFLUSH 

“RECEIVE DATA 

Flush the received data buffer when the 


INTERRUPT 

program enables the receive data 


ENABLE” 

interrupt. 


“NONE” 

Keep data in the received data buffer. 


“SWITCH TO 

Flush the received data buffer when the 


FOREGROUND” 

session is switched to the foreground. 


“ALL” 

Flush received data buffer in both 

situations. 

COM_SELECT 

“ALL” 

Do not limit the program’s access to 

COM ports. 


“COMx” 

Limit the program’s access to specified 

COM port. 


“NONE” 

Do not allow access to COM ports. 

DOS_AUTOEXEC 

pathname 

The fully qualified path of the batch file 
to execute when the session starts. 

C:\AUTOEXEC.BAT is the default. 

dos_background_ 

“r 

Allow the program to run in the 

EXECUTION 


background. 


“0” 

Stop the program when it is not in the 
foreground. 

DOS_BREAK 

“1” 

Activate Ctrl+C as a break character. 


“0” 

Do not activate Ctrl+C as a break 

character. 

DOS_DEVICE 

pathname, 

The fully qualified path for each DOS 


pathname,... 

device driver to load for this session. 

Separate each one with a comma. 

DOSJFCBS 

num 

The maximum number of file control 
blocks that can be opened in this 
session. This affects file-sharing modules 
(range 0-255). 

DOS_FCBS_KEEP 

num 

The number of file control blocks to set 
aside so they cannot be closed by the 
operating system (range 0-255). 

DOS_FILES 

num 

The maximum number of file handles 
that can be opened in this session. 
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Setting 

DOS_HIGH 

DOS_LASTDRIVE 

DOS_RMSIZE 

DOS_SHELL 

DOS_STARTUP_DRTVE 

DOSJUMB 

DOS_VERSION 


DPMI_DOS_API 


Value _ Description _ 

Load the DOS kernel above the 1MB 
memory address. 

Do not load the DOS kernel above the 
1MB memory address. 

The highest drive available to this 
session. Default is Z. 

The amount of memory available to this 
session. Range is 128K-640K; default is 
640. 

The path and file name for the 
command processor for this session. 

The drive letter or an image created 
with VMDISK to boot a specific version 
of DOS. 

“1” Allow DOS TSRs and devices to be 

loaded with LOADHIGH and 
DEVICEHIGH. 

“0” Give ownership of upper memory 

blocks to TSRs and devices 

version,version, Each version string is specified as: 

version... ProgramName A , Version A ,Sub Version A , 

repeat where repeat is the number of 
times this version can be reported to the 
program (255 for indefinite). For 
example: 

"SET DOS_VERSION= 

PROG1. EXE A ,3 / \30 / \255 / 

PROG2.EXE A ,3 A ,30 A ,255" 
to report to Progl.exe and Prog2.exe 
that the version of DOS is 3.3. 

The program comes with an extender 
based on DPMI and will perform 
memory translations. 

The operating system will perform the 
translation. 

The program does not use DPMI. 


“AUTO” 

“ENABLED” 

“DISABLED” 


“U 

“ 0 ” 

letter 

num 

filename 

letter or filename 
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Setting 

Value 

Description 

DPMI_MEMORY_LIMIT 

num 

The amount of DPMI available to this 
session (range 0-512MB). 

DPMI_NETWORK_BUFF_SIZE 

num 

The size of the network translation 
buffer for this DPMI program (range 

1-64KB). 

EMS_FRAME_LOCATION 

“AUTO” 

The session will locate expanded 
memory automatically. 


“NONE” 

Turn off the high EMS range. 


location 

The location of the 64KB EMS frame. 

For example: 

"SET EMS_FRAME_L0CATI0N=C400 " 

EMS_HIGH_OS_MAP_REGION 

num 

The amount of memory this program 
can add to the EMS (range 0-96KB). 

EMS_LOW_OS_MAP_REGION 

num 

The size of the remappable 
conventional memory available to this 
session (range 0-576KB). 

EMS_MEMORY_LIMIT 

num 

The amount of EMS memory available 
to this session (range 0-32768KB). 

HW_NOSOUND 

‘1” 

Prevent programs in this session from 
generating sounds. 



Allow programs to generate sounds. 

hygrom_to_ram 

“1” 

Copy ROM BIOS code to RAM. 


“0” 

Otherwise 

HW_TIMER 

tt r 

Give programs in this session direct 
access to hardware timer ports. 


“0” 

Otherwise 

IDLE_SECONDS 

num 

A period of allowable idle time before 
the operating system reduces processor 
time for this program (range 0-60 
seconds). 

IDLE_SENSITIVITY 

percentage 

Threshold for polling time before the 
operating system reduces processor 
time for this program (set to 100 to 
disable idle detection). 
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Setting 

Value 

Description 

INTJDURING_TO 

a r 

Allow interrupts during file reads and 
writes. 


“0” 

Otherwise 

KBD_ALTHOME_BYPASS 

u r 

Prevent switching from fullscreen to 
windowed when Alt+Home is pressed. 


“0” 

Otherwise 

KBD_BUFFER_ EXTEND 

“i” 

Increase the size of the keyboard 
typeahead buffer. 


“0” 

Do not extend the keyboard typeahead 
buffer. 

kbd_ctrl_bypass 

“NONE” 

Do not bypass any control-key 
sequences 


“ALT_ESC” 

Allow the program to process Alt+Esc. 


“CTRL_ESC” 

Allow the program to process Ctrl+Esc. 

KBD_RATE_LOCK 

“1” 

Prevent the program from changing the 
system keyboard repeat rate. 


“0” 

Otherwise 

MEM_EXCLUDE_REGIONS 

region A , 

Regions EMS/XMS cannot use because 


region A ,... 

they are needed for device drivers. 

MEM_INCLUDE_REGIONS 

region A , 

Regions EMS/XMS can use between 


region A ,... 

RMSIZE and IMB. 

MOUSE_EXCLUSIVE_ACCESS 

“1” 

Give this session exclusive ownership of 
the mouse. 


“0” 

Otherwise 

PRINT_SEPARATE_OUTPUT 

“1” 

Send seperate printer output if two 
programs in this session send to the 
same device. 


“0” 

Do not send separate output in this 
case. 

PRINT_TIMEOUT 

num 

The timeout before the operating 
system forces a print job to the printer 
(range 0-3600 seconds). 

SESSION_PRIORITY 

num 

The priority level for this session. Range 
is 1-32 (lowest to highest). 
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Setting 

Value 

Description 

VIDEO_8514AJKGAJOTRAP 

“1” 

Allow controlled access to the video 

device. 


“0” 

Provide unrestricted access. 

VIDEO_FASTPASTE 

“1” 

Speed up input from sources other thar 
the keyboard. 


“0” 

Otherwise 

VIDEO_MODE_RESTRICTION 

“NONE” 

Do not limit video mode support 


“CGA” 

Limit video mode support for CGA 
graphics. 


“MONO” 

Limit video mode support for text. 

VIDEO j3NDEMAND_MEMORY 

“1” 

Delay allocation of video-save buffers. 


“0” 

Otherwise 

VIDEO_RETRACE_EMULATION 

“1” 

Emulate text-based video ROM 

functions. 


“0” 

Otherwise 

VIDEO_SWITCH_NOTIFICATION 

“1” 

Notify the program when the session 
switches in and out of fullscreen mode. 


“0” 

Otherwise 

VIDEO_WINDOW_REFRESH 

num 

The window update frequency. Range is 
1-600 tenths of a second. 

XMSJHANDLES 

num 

The number of handles needed to 
identify XMS blocks (range 0-128). 

XMS_MEMORY_LIMIT 

num 

The amount of available XMS memory 
(range 0-16384 KB). 

XMS_MINIMUM_HMA 

num 

The minimum allocation size of the 
high memory area (range 0-63KB). 








Settings Page 
Methods 


The predefined Workplace Shell classes provide instance methods for 
adding each page to their settings notebooks. These methods can be 
called from the wpAddSettingsPages (pg. 181) override or can be re¬ 
moved by overriding the individual page method and returning SET- 
TINGS_PAGE_REMOVED. Each settings page instance method has 
the same parameters and return code. For example, the definition of 
wpAddObjectGeneralPage is: 

ULONG wpAddObjectGeneralPage (HWND hwndNotebook ) 

where hwndNotebook is the notebook window handle passed to the 
wpAddSettingsPages override and the return code is the page ID re¬ 
turned from wpInsertSettingsPage (pg. 183). The following is a list of 
the settings page methods for each class: 

Pass _ Method _ 

WPObject WpAddObjectGeneralPage 

wpAddObjectGeneralPage2 

wpAddObjectWindowPage 


WPFile System 


wpAddFile 1 Page 



Workplace Shell 


Class 


Method 


WPFileSystem 


WPDataFile 

WPFolder 


WPDesktop 


wpProgram and 
wpProgramFile 

WPLaunchPad 

WPClock 


WPCountry 


WPDisk 
WP Keyboard 


WPMouse 


wpAddFile2Page 

wpAddFile3Page 

wpAddFileMenuPage 

wpAddFileTypePage 

wpAddFolderBackgroundPage 

wpAddFolderlncludePage 

wpAddFolderSelfClosePage 

wpAddFolderSortPage 

wpAddFolderViewlPage 

wpAddFolderView2Page 

wpAddFolderView3Page 

wpAddDesktopLockup 1 Page 
wpAddDesktopLockup2Page 
wpAddDesktopLockup3Page 
wpAddDesktopArcRestlPage 
wpAddDesktopDefDTIPage 

wpAddProgramAssociationPage 

wpAddProgramPage 

wpAddProgramSessionPage 

wpAddLaunchPadPage 1 
wpAddLaunchPadPage2 

wpAddClockAlarmPage 
wpAddClockDateTimePage 
wpAddClockViewl Page 
wpAddClockView2Page 

wpAddCountry 

wpAddCountryNumbersPage 

wpAddCountryPage 

wpAddCountryTimePage 

wpAddDiskDetailsPage 

wpAddKeyboardMappingsPage 

wpAddKeyboardSpecialNeedsPa 

wpAddKeyboardTimingPage 

wpAddMouseCometPage 

wpAddMouseMappingsPage 

wpAddMousePtrPage 
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CSass 

Hethod 

WPMouse 

wpAddMouseTimingPage 

wpAddMouseTypePage 

WPSound 

wpAddSoundWarningBeepPage 

WPSystem 

wpAddSysFdrDefViewPage 

wpAddSysFdrSelfClosePage 

wpAddSystemConfirmationPage 

wpAddSystemlnputPage 

wpAddSystemLogoPage 

wpAddSystemPrintScreenPage 

wpAddSystemScreenPage 

wpAddSystemWindowPage 

wpAddTideConfirmationPage 



p 

Workplace 
Default Object IDs 


The following is a list of object IDs for objects created by the system. 
These default Workplace objects always have object IDs that begin with 


WP . 


Object ID 

<WP_DESKTOP> 
<WP_N O WHERE> 

<WP_TEMPS> 

<WP_VIEWER> 

<WP_SHRED> 

<WP_MINDEX> 

<WP_INFO> 

<WP_NETWORK> 

<WP_GLOSS> 

<WP_TUT OR> 


Description _ 

Desktop folder 

Nowhere folder: an invisible folder for placing 
objects that should not be in a folder. 

Templates folder 

Minimized Window Viewer 

Shredder 

Master Help Index 
Information Folder 
Network Folder 
Glossary 
Tutorial 
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Object ID 

Description 

<WP_CMDREF> 

Command Reference 

<WP_OS2SY5> 

OS/2 System folder 

<WP_DRIVES> 

Drives folder 

<WP_START> 

Startup folder 

<WP_CONFIG> 

System Setup folder 

<WP_CFOCK> 

Clock 

<WP_KEYB> 

Keyboard 

<WP_MOUSE> 

Mouse 

<WP_SOUND> 

Sound 

<WP_SY5TEM> 

System 

<WP_CNTRY> 

Country 

<WP_FNTPAL> 

Font Palette 

<WP_CLRPAL 

Color Palette 

<WP_SCHPAL> 

Scheme Palette 

<WP_PROMPTS> 

Command Prompts 

<WP_GAMES> 

Games folder 

<WP_TOOLS> 

Productivity 

< WP_LAUN CHPAD> 

Launch Pad 





Predefined Views 


The following is a list of views supported by the system. 


Class 

View 

Value 

WPObject 

OPEN_SETTIN GS 

2 

WPFolder 

OPEN_CONTENTS 

1 


OPEN_TREE 

101 


OPEN_DETAILS 

102 

WPDisk 

OPEN_AUTO 

120 

WPProgram and 
WPProgramFile 

OPEN_RUNNING 

4 

WPPalette 

OPEN_PALETTE 

121 
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Device Object 
Settings 


The following list contains the device object settings for WPSystem, 
WPMouse, and WPKeyboard. These settings can be queried and set 
with wpclsOuerySetting (pg. 126) and wpclsSetSetting (pg. 131). 


Class 


Setting 


Value 


WPSystem Animation 


ConfirmCopyMove 

CreateShadow 


ANIMATION_ON—Enable window 
animation. 

ANIMATION_OFF—Disable window 
animation. 

ANIMATION_D EFAULT—Use the system 
default. 

CONFIRM ON—Confirm copy, move, and 
create shadow operations. 

CONFIRM_OFF—Do not confirm these 
operations. 

CONFIRM DEFAULT—Use the system 
default. 
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Class 

WPSystem 


Setting 


Value 


ConfirmFolderDelete CONFIRM ON—Confirm folder deletion. 

CONFIRMOFF—Do not confirm folder 
deletion. 

CONFIRM_DEFAULT—Use the system 
default. 


ConfirmObjectDelete CONFIRM_ON—Confirm object deletion. 

CONFIRM_OFF—Do not confirm object 
deletion. 

CONFIRM_DEFAULT—Use the system 
default. 

ConfirmRenameFileExtension CONFIRM_ON—Display confirmation dialog 

when user changes the extension of a file. 
CONFIRM_OFF—Do not display the 
confirmation dialog. 

CONFIRM_DEFAULT—Use the system 
default. 


ConcurrentView 


DisplayProgressIndicator 


LogoDisplayTime 


MinButtonAppearance 


CCVIEW_ON—Allow concurrent views. 
CCVIEW_OFF—Disallow concurrent views. 
CCVIEW_DEFAULT—Use the system default. 

DISPLAY_ON—Display the progress 
indicator for copy, move, and delete 
operations. 

DISPLAY_OFF—Do not display the progress 
indicator. 

DISPLAY_DEFAULT—Use the system 
default. 

LOGOJNDEFINITE—Display logos until 
they are dismissed. 

LOGO_NONE—Do not display application 
logos. 

n—The amount of time, in milliseconds, to 
display logos. 

BUTTON_HIDE—Use hide buttons for 
views. 

BUTTON_MINIMIZE—Use minimize 
buttons for views. 

BUTTON_DEFAULT—Use the system 
default. 
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Class 

WPSystem 


WPMouse 


Setting 

NameClash 


PrintScreen 


ButtonSetup 


DisplayWindowListButton 


BoubleClickTime 


DragObjectButton 


EditTitleTextButton 


Value 

NAMECLASHPROMPT—Prompt the user 
when an object title clash occurs. 

NAMECLASH_RENAME—Rename an object 
when title clash occurs. 
NAMECLASH_REPLACE—Replace the 
duplicate object when a title clash occurs. 

PRINTSCREEN_ON—Enable print screen. 
PRINTSCREEN_OFF—Disable print screen. 

BUTTONS_LEFTHANDED—Left-handed 
mouse. 

BUTTONS_RIGHTHANDED—Right-handed 
mouse. 

High word: INP_NONE—Required if default 
not used. 

Low word: WM_BUTTON2CLICK or 
WM_CHORD 

WINDOWLISTBUTTONJDEFAULT—Use 
the system default. 

n—Time between mouse clicks. 

Range is 170-1060. 

DOUBLECLICKJDEFAULT—Use the 
system default. 

High word: INP NONE—Required if default 
not used. 

Low word: WM_BUTTONlMOTIONSTART 
or WM_BUTTON2MOTIONSTART 
DRAGBUTTON_D EFAULT—Use the system 
default. 

High word: INP_ALT—Key to press with 
mouse button to edit title text. 

INPCTRL 

INP_NONE 

INP_SHIF 

Low word: WMJBUTTON 1 CLICK 
WM_BUTTON2 CLICK 
WM_BUTTONlDBLCLK 
WM_BUTTON2DBLCLK 
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Class 


WPKeyboard 


Setting 


PopupMenuButton 


TrackingSpeed 


CursorBlinkRate 


EditTideTextKey 


Value 


TEXTEDITBUTTON_DEFAULT—Use the 
system default. 

High word: INP_ALT—Key to press with 
mouse button to display a pop-up menu. 
INPCTRL 
INP_NONE 
INP_SHIFT 

Low word: WM_BUTTONl CLICK 
WM_BUTT ON 2_CLICK 
WM_BUTT ON2DBLCLK 
WM_CHORD 

POPUPBUTTON_DEFAULT—Use the 
system default. 

n—Mouse tracking speed 
(range 1-7). 

n—Cursor blink rate. Range is CURSOR- 
BLINK_MIN to CURSORBLINKJMAX. 
CURSORBLINK_DEFAULT—Use the system 
default. 


High word: (OR flags together) 


AF_VIRTUALKEY 

AE_KBDCOMMAND 

AE_ALT 

AE_SHIFT 

AF_CONTROL 


Required if default 
not used. 

Required if default 
not used. 

Include Alt in key 
sequence. 

Include Shift in key 
sequence. 

Include Ctrl in key 
sequence. 


Low word: VK_*—Key to start title text 
editing. 

TEXTEDITKEY_DEFAULT—Use the system 
default. 
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Class 

Setting 

Value 

WPKeyboard 

KeyRepeatRate 

n—Key repeat rate. Range is 
REPEATRATE_MIN to REPEATRATE_MAX. 



REPEATRATE_DEFAULT—Use the system 
default. 


KeyRepeatDelay 

n—Key repeat delay. Range is REPEAT- 
DELAY_MIN to REPEATDELAY_MAX. 



REPEATDELAY_DEFAULT—Use the system 
default. 


PopupMenuKey 

High word: (OR flags together) 
AF_VIRTUALKEY—Required if default not 
used. 

AE_KB DCOM MAN D—Required if default 
not used. 

AF_ALT—Include Alt in key sequence. 
AFSHIFT—Include Shift in key sequence. 
AF_CONTROL—Include Ctrl in key 
sequence. 

Low word: VK_*—Key to summon pop-up 
menus. 



P O P UP KEY__D EFAU LI—Use the system 
default. 






<class name>GetData, 392 
<class name>MethodDebug, 393 
<class name>NewClass, 394 
_<class name>, 395 

A 

ACTION_BUTTONS_* values, 304 
ACTIONS, 323 

Associations, 269, 270, 271-276, 280-282 
ASSOCTABLE, 269 

B 

Base class, 3 
BKA_* flags, 188 

C 

CANCEL_DELETE, 41, 52 
CCVIEW_ values, 164 
CELL, 335 

CFA_* flags, 132-133 
Class(es) 

data, see class data 
deregistering, 12, 28 
enumerating, 14, 32 
icons, 105, 124, 130, 260, 262 
installing, 6 
locking, 70 
method, 4 
module, 373, 399 
pointer, 4 
querying, 395-398 
registering, 33 
replacing, 19, 375 
styles, 127 
title, 104, 129 
unlocking, 69 
usage count, 69, 70 
Class data, 78 
initializing, 79, 101 
saving, 79 

uninitializing, 79, 102 


CLASSFIELDINFO, 132 
CLSSTYLE_* flags, 127-128 
CMP* values, 135 
COMPARESUPPORTED, 134 
CONFIRMJDELETE, 41, 52 
CONFIRM_DELETEFOLDER, 41, 52 
CONFIRM,* flags, 111 
Container records, 107, 112 
CO_* values, 10 
CRA_* flags, 107 
CTXT_* flags, 193-194 
CV_* flags, 246 

B 

Data files, see WPDataFile 
DEFAULTBUTTON, 162 
Desktop, wWPDesktop 
Details data: 

column visibility, 239, 247, 252, 254 
refreshing, 106 
sample code, 138-143 
sorting, 240, 250, 257, 258 
specifying, 113, 123 
Device class, 4, 105, 126, 131, 421 
Device object, see Device class 
DEVOPENSTRUC, 370 
Dirty objects, 79 
Disk objects, see WPDisk 
DM DRAGOVER, s^wpDragOver 
DM_DROP, .w wpDrop 
DO_* flags, 203 
DOR_* values, 203 
DOS Settings, 409 
Drag/Drop, 200 

from Workplace, 201 
to Workplace, 201 
DRAGINFO, 211 
DRAGITEM, 212 
DRF_OBJECT, 201 
Drive objects, see WPDisk 
DRMJDBJECT, 201 
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Index 


E 

Error handling, 371, 374-375, 384-385 
Exit list, 103 

Extended Attributes, 213 

F 

FDATE, 228 
FILE_* flags, 216 
Finding objects, 371, 376-383 
Folder, s^WPFolder 
FTIME, 228 

H 

Handles, see object handles 
Help, 337 

default, 340-341, 342 
displaying, 338 
for pop-up menus, 339 
for settings notebooks, s^PAGEINFO 
HIDEBUTTON, 162 

I 

XCONINFO, 136 
Installation, 6 
Instance data, 78 
accessing, 392 
allocating, 79, 80 
freeing, 79, 82 
initializing, 79, 83 
restoring, 79, 84, 87-91 
saving, 21, 33, 79, 92-100 
uninitializing, 79, 100 
In-use list, 144, 157 

L 

Eaunch Pad, scr WPLaunchPad 
LINKITEM, 153 

M 

MEMORYITEM, 153 
MENU_* values, 192 
MINBUTTON, 162 
MINWIN_* values, 166 

N 

NOJDELETE, 41, 52 
Notebook, see Settings notebook 
Nowhere folder, 5, 234, 301 


O 

OBJCLASS, 36 
Object(s): 

asleep, see object, dormancy 
awake, 38, 73 
copying, 8, 24, 44 
creating, 9, 25, 47, 71 
data, see instance data 
deleting, 13, 29, 51, 53-54 
dormancy, 38-39 
handles, 7, 17, 60, 72 
icons, 105, 114, 115, 119, 120 
IDs, 7-8, 117, 418 
lock count, 38, 55 
locking, 38-39, 55, 56 
moving, 16, 30, 57 
opening, see views, opening 
printing, 344, 350 
saving, see instance data, saving 
settings, 104 
styles, 108, 118, 121 
tide, 104, 118, 122 
unlocking, 38-39, 65 
OBJECTJFROMJPREC, 234 
OBJECTSNOOZETIME, 38 
OBJSTYLE_* flags, 108-109 
O BJ STYLE_N O SETTIN GS, 109, 110 
OD_* values, 369 
OKJDELETE, 41, 52 
OPENJJSER, 156, 160 
OR_* flags, 59 

P 

PAGEINFO, 187 
Palettes, .wWPPalette 
PALINFO, 335 
PD_JOB_PROPERTY, 369 
Persistent handles, see object handles 
PMSHELL.EXE, 2, 7 
PO_* flags, 367 
POINTL, 137 
Pop-up menus, 190 

adding items, 190, 195, 199 
displaying, 191 
filtering items, 190, 193 
Presentation Manager, 1 
PRINTDEST, 369 
Printers, see WPPrinter 
PROGDETAILS, 284 
Program objects, see WPProgram(File) 
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PROGTYPE, 284 
PROG_* values. 285 

Q 

QC_* values, 244 

R 

RC_DROP_* values, 207 
RECORDINSERT, 267 
RECORDITEM, 153 
RECTL, 336 

*_RENAMEFILESWITHEXT values, 271 
REXX, 6-8, 23 

S 

Settings notebook, 180 
adding pages, 180 
removing pages, 181, 415 
sizing, 185-186 
Settings page methods, 415 
SETTIN GS_PAGE_NUMBERS, 188 
SETTINGSJPAGKJREMOVED, 181, 415 
Setup strings, 61, 63, 64, 401 
Shadow objects, see WPShadow 
SHE_* flags, 285 
SIZEL, 189 

somDescendedFrom, 398 
SOMError, 386 
somFree, 387 
somGetClass, 5, 395 
somGetClassName, 396 
somldFromString, 389 
somlnit, 387 
SOMInitModule, 387 
somlsA, 397 
somlsInstanceOf, 397 
somLocateClassFile, 399 
somLPrintf, 390 
somNew, 387 

SOMOutCharRoutine, 388 

somPrintf, 391 

somRegisterClass, 387 

SOMSTARS, 387 

somUnlnit, 387 

SORTBYSUPPORTED, 134 

Sorting, see Details data, sorting 

Source rendering, see wpFormatDragltem 

Storage class, 3 

SysCopyObject, 24 

SysCreateObject, 25 


SysCreateShadow, 27 
SysDeregisterObjectClass, 28 
SysDestroyObject, 29 
SysMoveObject, 30 
SysOpenObject, 31 
SysQueryClassList, 32 
SysRegisterObjectClass, 33 
SysSaveObject, 33 
SysSetObjectData, 34 
System Object Model, 1, 386 

T 

Templates, 43, 48, 67 

U 

USAGEJLINK, 51, 146, 148, 150, 297 
USAGEJMEMORY, 81, 83, 146, 150 
USAGE_OPENFILE, 146, 150 
U SAGE_OPENVIEW, 144, 146, 148, 150 
USAGE_RECORD, 146, 148, 150 
USEITEM, 144, 154 
USERWORDJFROMJPREC, 234 

V 

VTEWFILE, 154 
VIEW_* flags, 152 
VIEWITEM, 155 
Views, 156 
closing, 158 
concurrent, 164, 170 
default, 157, 165, 171, 178 
fonts, see WPFolder fonts 
hiding, 159 

minimize behavior, 166, 172 
minimize button appearance, 162, 169, 177 
opening, 16, 31, 157, 160, 164, 170, 174 
predefined, 420 
registering, 157, 167 
restoring, 168, 173 
VIEWSTATE_* flags, 155 

W 

WinCopyObject, 8 
WinCreateObject, 7, 9 
WinCreateShadow, 11 
WinDeregisterObjectClass, 12 
WinDestroyObject, 13 
WinEnumObjectClasses, 14 
WinMoveObject, 16 
WinOpenObject, 16 
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WinQueryObject, 17 
WinRegisterObjectClass, 2, 6, 11, 18 
WinReplaceObjectClass, 4, 19 
WinSaveObject, 21 
WinSetObjectData, 22 
Workplace Classes, 2-4 
WPAbstract, 3-4, 38, 79 
wpAddFirstChild, 231 
wpAddSettingsPages, 180, 181 
wpAddToContent, 232 
wpAddToObjUseList, 144, 145, 156 
wpAllocMem, 80 
WPClock, 3-4 
wpClose, 158 

wpclsCreateDefaultTemplates, 67 
wpclsDecUsage, 69 
wpclsFindObjectEnd, 376 
wpclsFindObjectFirst, 377 
wpclsFindObjectNext, 382 
wpclsFindOneObject, 383 
wpclsInitData, 101 
wpclsInsertMultipleObjects, 264 
wpclsNew, 71 

wpclsObjectFromHandle, 72 
wpclsQueryActiveDesktop, 259 
wpclsQueryActiveDesktopHWND, 260 
wpclsQueryAwakeObject, 73 
wpcisQueryButtonAppearance, 177 
wpclsQueryDefaultHelp, 342 
wpclsQueryDefaultView, 178 
wpclsQueryDetailsInfo, 123 
wpclsQueryEditString, 334 
wpclsQueryError, 384 
wpclsQueryFolder, 74 
wpclsQuerylcon, 105 
wpclsQuerylconData, 124 
wpclsQuerylconDataN, 260 
wpclsQuerylconN, 262 
wpclsQuerylnstanceFilter, 227 
wpclsQuerylnstanceType, 226 
wpclsQueryObject, 75 
wpclsQueryObjectFromFrame, 179 
wpclsQueryObjectFromPath, 76 
wpclsQueryOpenFolders, 262 
wpclsQuerySetting, 4, 126, 421 
wpclsQuerySettingsPageSize, 185 
wpclsQueryStyle, 127 
wpclsQueryTitle, 129 
wpclsRemoveObjects, 265 
wpclsSetError, 385 


wpclsSetlcon, 130 
wpclsSetlconData, 130 
wpclsSetSetdng, 4, 131, 421 
wpclsSetSettingsPageSize, 186 
wpclsUnlnitData, 102 
wpCnrlnsertObject, 233 
wpCnrRefreshDetails, 106 
wpCnrRemoveObject, 234 
wpCnrSetEmphasis, 107 
wpConfirmDelete, 40 
wpConfirmKeepAssoc, 270 
wpContainsFolders, 235 
wpCopiedFromTemplate, 43 
wpCopyObject, 44 
WPCountry, 3-4 
wpCreateAnother, 47 
wpCreateFromTemplate, 48 
wpCreateShadowObject, 50 
wpCreateShadowObjectExt, 296 
WPDataFile, 214 

associations, see Associations 
icon, 271, 280 
printing, 349-362 
wpDelete, 51 
wpDeleteAHJobs, 346 
wpDeleteContents, 236 
wpDeleteFromContent, 237 
wpDeleteFromObjUseList, 148 
WPDesktop, 238, 259, 260 
WPDisk, 286 
ejecting, 287 
icon, 293 
locking, 289, 291 
logical drive, 292 
querying, 290 

root folder, see WPRootFolder 
wpDisplayHelp, 338 
wpDisplayMenu, 191 
wpDragCell, 327 
wpDraggedOverObject, 202 
wpDragOver, 204 
wpDrop, 206 

wpDroppedOnObject, 209 
wpEditCell, 328 
wpEndConversation, 202 
WPFileSystem, 3-4, 38, 79, 213 
wpFilterPopupMenu, 193 
wpFindMinWindow, 372 
wpFindUseltem, 150 
wpFindViewItem, 152 
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WPFolder, 213, 229 

animation icon, 260, 262 
contents, 229, 232, 235-237, 242-243 
details class, 247, 254 
folder flags, 241, 248, 255 
fonts, 248, 256 
icon positions, 251 
querying, 251 
refreshing, 222 
sort class, 250, 257 
view attributes, 245, 253 
wpFormatDragltem, 209 
wpFree, 53 
wpFreeMem, 82 
wpHide, 159 
wpFIoldPrinter, 346 
wpInitData, 83 

wpInsertPopupMenuItems, 195 
wpInsertSettingsPage, 180, 183 
wpIsCurrentDesktop, 238 
wpIsDeleteable, 54 
wpIsDetailsColumnVisible, 239 
wpIsDiskSwapped, 288 
wpIsLocked, 55 
wpIsObjectlnitialized, 56 
wpIsSortAttribAvailable, 240 
wpJobAdded, 347 
wpJobChanged, 348 
wpJobDeleted, 348 
WPKeyboard, 3-4 
WPLaunchPad, 301 

action buttons, 303-304, 313 
closing drawers, 305, 314 
contents, 311, 320-322 
frame controls, 310, 319 
icon size, 304-305, 314 
orientation, 308-309, 317-318 
refreshing, 312 
text, 306-307, 315-316 
wpLockDrive, 289 
wpLockObject, 39, 56 
WPMENUID* values, 196 
wpMenuItemHelpSelected, 339 
wpMenuItemSelected, 198 
wpModifyFldrFlags, 241 
wpModifyPopupMenu, 199 
wpModifyStyle, 108 
wpModuleForClass, 373 
WPMouse, 3-4 
wpMoveObject, 57 


WPObject, 2 
wpObjectReady, 58 
wpOpen, 160 
wpPaintCell, 329 
WPPalette, 325 
wpPopulate, 242 
WPPower, 3-4 
WPPrinter, 344 

computer name, 363 
creating, 345 
default, 366 
jobs, 346-348 
physical name, 363 
queue, 346, 362, 364, 367 
wpPrintMetaFile, 349 
wpPrintObject, 350 
wpPrintPifFile, 358 
wpPrintPlainTextFile, 359 
wpPrintPrinterSpecificFile, 360 
wpPrintUnknownFile, 361 
WPProgram(File), 268 

associations, see Associations 
details, 277, 283 
screen group ID, 279 
wpQueryActionButtons, 303 
wpQueryActionButtonStyle, 304 
wpQueryAssociatedFilelcon, 271 
wpQueryAssociatedProgram, 269, 272 
wpQueryAssociationFilter, 275 
wpQueryAssociationType, 276 
wpQueryAttr, 215 
wpQueryButtonAppearance, 162 
wpQueryCloseDrawer, 305 
wpQueryComputerName, 363 
wpQueryConcurrentView, 164 
wpQueryConfirmations, 111 
wpQueryContainer, see wpQueryFolder 
wpOueryContent, 243 
wpQueryCoreRecord, 112 
wpQueryCreation, 216 
wpQueryDefaultHelp, 340 
wpQueryDefaultView, 165 
wpQueryDisk, 290 
wpQueryDisplaySmalllcons, 305 
wpQueryDisplayText, 306 
wpQueryDisplayTextlnDrawers, 307 
wpQueryDisplayVertical, 308 
wpQueryDrawerHWND, 308 
wpQueryDriveLockStatus, 291 
wpQueryEASize, 217 
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wpQueryError, 374 
wpQueryFileName, 214 
wpQueryFileSize, 218 
wpQueryFldrAttr, 245 
wpQueryFldrDetailsClass, 247 
wpQueryFldrFlags, 248 
wpQueryFldrFont, 248 
wpQueryFldrSortClass, 250 
wpQueryFloatOnTop, 309 
wpQueryFolder, 251 
wpQueryHandle, 60 

wpQueryHideFaunchPadFrameCtls, 310 
wpQuerylcon, 114 
wpQuerylconData, 115 
wpQueryLastAccess, 219 
wpQueryLastWrite, 219 
wpOueryLogicalDrive, 292 
wpQueryMinWindow, 166 
wpQueryNextlconPos, 251 
wpQueryObjectID, 117 
wpQueryObjectList, 311 
wpQueryPalettelnfo, 330 
wpQueryPrinterName, 363 
wpQueryProgDetails, 277 
wpQueryQueueOptions, 364 
wpQueryRealName, 220 
wpQueryRemoteOptions, 365 
wpQueryRootFolder, 293 
wpQueryScreenGroupID, 279 
wpQueryShadowedObject, 298 
wpQueryStyle, 118 
wpQueryTide, 118 
wpQueryType, 221 
wpRedrawCell, 330 
wpRefresh, 222 
wpRefreshDrawer, 312 
wpRegisterView, 156, 167 
wpReleJIePrinter, 362 
wpRender, 202 
wpRenderComplete, 202 
wpReplacemendsInEffect, 375 
wp Restore, 168 
wpRestoreData, 84 
wpRestoreLong, 87 
wpRestoreState, 89 
wpRestoreString, 90 
WPRootFolder, 286 

querying from WPDisk, 293 
wpSaveData, 92 
wpSaveDeferred, 79, 94 


wpSavelmmediate, 79, 95 
wpSaveEong, 96 
wpSaveState, 97 
wpSaveString, 98 
wpScanSetupString, 61 
wpSelectCell, 331 
wpSetActionButtonStyle, 313 
wpSetAssociatedFilelcon, 280 
wpSetAssociationFilter, 281 
wpSetAssociationType, 282 
wpSetAttr, 223 

wpSetButtonAppearance, 169 
wpSetCloseDrawer, 314 
wpSetConcurrentView, 170 
wpSetCorrectDisklcon, 293 
wpSetDefaultHelp, 341 
wpSetDefaultPrinter, 366 
wpSetDefaultView, 171 
wpSetDetailsColumnVisibility, 252 
wpSetDisplaySmalllcons, 314 
wpSetDisplayText, 315 
wpSetDisplayTextlnDrawers, 316 
wpSetDisplayVertical, 317 
wpSetDrawerHWND, 317 
wpSetError, 375 
wpSetFldrAttr, 253 
wpSetFldrDetailsClass, 254 
wpSetFldrFlags, 255 
wpSetFldrFont, 256 
wpSetFldrSortClass, 257 
wpSetFloatOnTop, 318 
wpSetHideFaunchPadFrameCtls, 319 
wpSetlcon, 119 
wpSetlconData, 120 
wpSetLinkToObject, 299 
wpSetMinWindow, 172 
wpSetNextlconPos, 231 
wpSetObjectID, 118 
wpSetObjectFistFromHObjects, 320 
wpSetObjectListFromObjects, 321 
wpSetObjectListFromStrings, 322 
wpSetPalettelnfo, 332 
wpSetProgDetails, 283 
wpSetQueueOptions, 367 
wpSetRealName, 215 
wpSetRemoteOptions, 368 
wpSetShadowTitle, 300 
wpSetSortAttribAvailable, 258 
wpSetStyle, 121 
wpSetTitle, 122 
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wpSetType, 224 
wpSetup, 63 
wpSetupCell, 333 
wpSetupOnce, 64 
WPShadow, 295 

creating, 11, 27, 50, 296 
original object, 295, 298 
setting a link, 299 
title, 300 

WPShredder, 3-4 


WPSound, 3-4 
wpSwitchTo, 157, 173 
WPSystem, 3-4, 164, 170, 172 
WPTransient, 3-4, 39, 46 
wpUnlnitData, 100 
wpUnlockObject, 39, 65 
wpVerifyUpdateAccess, 225 
wpViewObject, 174 
wpWaitForClose, 176 
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